├── .gitignore ├── README.md └── sections └── reviews.md /.gitignore: -------------------------------------------------------------------------------- 1 | .projectile 2 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Open Knowledge Foundation Coding Standards 2 | 3 | This document outlines coding standards for use at Open Knowledge Foundation. It is a living document, and we encourage pull request and issues to improve on or contest ideas as expressed. 4 | 5 | ## Related documents 6 | 7 | * [Code reviews](sections/reviews.md): A description of our general code review process at Open Knowledge Foundation. 8 | 9 | ## TL;DR 10 | 11 | * We use Python and Javascript (Node.js). If you plan to develop in another language please flag this and discuss. 12 | * Tests are required. Unit tests, as well as functional and integration tests. Aiming for test coverage of 80% and above is desirable. 13 | * Tests must be automated via a continuous integration platform that is triggered when code is pushed to the canonical repository. 14 | * Documentation is required for all code. Documentation is just as important as tests. 15 | * Document functions, classes, modules and packages with docstrings. 16 | * Provide a great `README.md` file with examples of how to use the code. 17 | * Only use documentation builders like Sphinx for large projects; prefer `README.md` files for brevity and accessibility of documentation. 18 | * Use spaces and never tabs. 19 | * Javascript, HTML and CSS: 2 space indentation. 20 | * Python: 4 space indentation. 21 | * Strictly enforce a 79 character line limit. 22 | * Lint Javascript with `eslint`; Lint Python using `pylint`. 23 | * Use common language conventions for naming functions, classes and variables. 24 | * Code should be submitted via pull requests, which another person should merge. 25 | * Use continuous deployment. 26 | * Apps should be deployed from Travis when a successful build is made on the branch used for production. 27 | * Packages should be published to the respective package registry when a tag is pushed. 28 | * Write small, reusable libraries where possible. There are many opportunities for reuse across our different products. 29 | * We support modern browsers. Notably, IE 10 and above. Our browser support is in sync with the browser support of Google web properties, as [declared here](https://support.google.com/a/answer/33864?hl=en) 30 | 31 | --- 32 | 33 | ## Languages 34 | 35 | Our work is done in Python and Javascript (Node.js). There can be good reasons for writing a particular library or app in another language, but if you think this is the case, please raise this issue directly before starting any work. 36 | 37 | For example apps that implement the OKF preferences, see the following: 38 | 39 | * [oki lib in Javascript](https://github.com/okfn/oki-js) 40 | * [oki lib in Python](https://github.com/okfn/oki-py) 41 | 42 | ## Style and linting 43 | 44 | ### Python 45 | 46 | 1. Follow the Python Style Guide (PSG) as formulated in PEP-8: http://www.python.org/dev/peps/pep-0008/ 47 | 2. Use `pylint` to lint code. 48 | 49 | The critical points are: 50 | 51 | * Use spaces; never use tabs 52 | * 4 space indentation 53 | * 79 character line limit 54 | * Variables, functions and methods should be `lower_case_with_underscores` 55 | * Classes are `TitleCase` 56 | 57 | And other preferences: 58 | 59 | * Use ' and not " as the quote character by default 60 | * When writing a method, consider if it is really a method (needs `self`) or if it would be better as a utility function 61 | * When writing a `@classmethod`, consider if it really needs the class (needs `cls`) or it would be better as a utility function or factory class 62 | 63 | #### Python 2/3 64 | 65 | As a rule, all Python code should be written to support Python 2 and Python 3. There are some circumstances where, for new apps, we may want to write specifically for the Python 3 interpreter in order to take advantage of great new language features like `asyncio`, but at this stage, this is likely an exception and not the rule. No code should be written to be compatible with Python 2 only. 66 | 67 | The [python porting guide](https://docs.python.org/3/howto/pyporting.html) has great, practical advice on writing code for Python 2 and 3. Some choose to use helper libraries like [`six`](https://pypi.python.org/pypi/six). In any case, it is strongly recommend to follow the advice from the Python porting guide and add the following snippet to all Python modules to ensure API consistency for strings, division, imports, and the print function. 68 | 69 | ``` 70 | # -*- coding: utf-8 -*- 71 | from __future__ import division 72 | from __future__ import print_function 73 | from __future__ import absolute_import 74 | from __future__ import unicode_literals 75 | ``` 76 | 77 | ### Javascript 78 | 79 | 1. Use `eslint` to lint code. 80 | 2. Prefer to write all new code in `ES6` and compile/transpile with Webpack or Browserify. This applies to frontend and backend code. In some cases, the cost of transpilation (inflated file size) is too great (for small utility libraries), so use judgement. 81 | 82 | The critical points are: 83 | 84 | * Use spaces; never use tabs 85 | * 2 space indentation 86 | * 79 character line limit 87 | * Variables, functions and methods should be `camelCase` 88 | * Classes are `TitleCase` 89 | 90 | And other preferences: 91 | 92 | * Don't use semi-colons in `ES6` or any code that you are transpiling - it is quite unnecessary. 93 | 94 | ## Testing 95 | 96 | ### Python 97 | 98 | 1. Use `tox` with `py.test` to test code. 99 | 100 | ### Javascript 101 | 102 | 1. Use `mocha` to test code. 103 | 2. Use `Zombie.js` or `jsdom` for tests that require a DOM. 104 | 105 | ## Documentation 106 | 107 | ### Python 108 | 109 | #### Docstrings 110 | 111 | Use Sphinx-style or Google-style documentation conventions. 112 | 113 | * http://packages.python.org/an_example_pypi_project/sphinx.html#function-definitions 114 | * https://google.github.io/styleguide/pyguide.html#Comments 115 | 116 | #### User documentation 117 | 118 | Prefer to make really good `README.md` files, rather than implementing a full documentation framework. 119 | 120 | ### Javascript 121 | 122 | #### Docstrings 123 | 124 | Use Google-style documentation conventions. 125 | 126 | * https://google.github.io/styleguide/javascriptguide.xml#Comments 127 | 128 | #### User documentation 129 | 130 | Prefer to make really good `README.md` files, rather than implementing a full documentation framework. 131 | 132 | ## Frameworks 133 | 134 | We prefer the following frameworks and libraries. If you want to use an *alternative to one of these please flag this before starting any work. 135 | 136 | ### Python 137 | 138 | * Flask 139 | * Click 140 | 141 | ### Javascript 142 | 143 | * lodash 144 | * Express 145 | * React 146 | * Angular 147 | 148 | ## Version control 149 | 150 | We use Git for all projects. 151 | 152 | ### Branch management 153 | 154 | We generally follow Git Flow, with some modifications, and some flexibility per project. The following should hold true for pretty much all projects: 155 | 156 | * Have a `master` branch 157 | * Never commit directly to `master` 158 | * Always work from a `feature/{}` or a `fix/{}` branch that is checked out from `master` 159 | * Always reference issues from Git messages using `#{issue_id}`, and the various other related conventions used by most Git hosts. 160 | * Properly describe changes in commit messages: "Fixes database migration script failure on Python 2.7", not "Fix." 161 | * Prefer to use the "Squash and merge" approach for pull requests using GitHub web interface 162 | 163 | ## Continuous integration and deployment 164 | 165 | All projects must be configured with a CI server. We use Travis CI by default. The CI server must run the test suite with linting. 166 | 167 | ## App deployment 168 | 169 | All apps must be deployed from the CI server. 170 | 171 | ## Package publication 172 | 173 | All packages must be published to npm and pypi from the CI server. The procedure is: 174 | 175 | 1. Create your package and prepare it for publication. 176 | 2. Register the package on the appropriate registry. 177 | 3. Give the `okfn` user owner rights on the package. 178 | 4. Create tags for package versions. 179 | 5. Use the Travis integration to publish on tags. 180 | 181 | ## Web apps 182 | 183 | ### URLs 184 | 185 | * In general do not use trailing slash on urls (but ensure you redirect 301 from trailing slash to non-trailing slash) 186 | * e.g.: /work not /work/, /work/9 not /work/9/ 187 | 188 | ### RESTful APIs 189 | 190 | * Use plural versions of entities names for endpoints 191 | * When implementing RESTful APIs, keep them RESTful, but don't hesitate to create endpoints that are not RESTful when it is practical 192 | 193 | ### Browser support 194 | 195 | We support modern browsers. Notably, IE 10 and above. Our browser support is in sync with the browser support of Google web properties, as [declared here](https://support.google.com/a/answer/33864?hl=en) 196 | 197 | ## Further reading 198 | 199 | * http://docs.python-guide.org/en/latest/ 200 | -------------------------------------------------------------------------------- /sections/reviews.md: -------------------------------------------------------------------------------- 1 | # Code reviews 2 | 3 | At Open Knowledge Foundation (OKF) all code must be reviewed by a colleague before merging into the main branch of the repository (usually `master`). This short document examples how to do code reviews, and why we do it. 4 | 5 | ## How 6 | 7 | The process for code reviews is straight forward as long as you are already following our coding standards for working with version control, and in particular our git flow-influenced process of branch management. The bottom line is that, before any code hits `master`, it must be reviewed by a colleague. 8 | 9 | ### Submitting code for review 10 | 11 | Submitting code for review should follow these steps: 12 | 13 | 1. Always, always work from a feature or fix branch that is checked out of `master`. 14 | 2. Each feature or fix branch should be focused on a discrete unit of work. 15 | 3. When your unit of work is complete, submit a pull request against the `master` branch on `origin`. Ensure your [commit message](https://github.com/okfn/coding-standards#version-control) is communicative. 16 | 4. Wait for the CI server to run, validating your tests pass on all target environments. If you do not have tests, or have not configured CI, do that immediately before proceeding. 17 | 5. If CI is green, ask a colleague to review your pull request (we will automate this in the near future). This preferably will be a colleague who is not working on your project. 18 | 6. Address any questions from the code review. Sometimes this will involving refactoring, other times it will just mean answering questions. 19 | 7. When the reviewer indicates that the pull request is ready to merge, you may merge into `master`. It is *recommended* that the developer merge her own branch into master, due to the cross-project review process (the developer can decide the best time to merge, after the review has approved the merge). 20 | 8. **If** your branch was a branch on the main repository (usually `origin`), then you must also remove your branch to reduce clutter. 21 | 22 | ### Reviewing code in a pull request 23 | 24 | Reviewing someone else's code should follow the following steps: 25 | 26 | 1. Respond to a request for a code review immediately. Indicate when you can do it ("now", "in the next hour", and so on). 27 | 2. Review the pull request, using inline commenting for specific issues. 28 | 3. If you are satisfied with the pull request (without any questions, or after your questions have been answered), then explicitly state that the pull request is ready to be merged as a comment on the pull request. 29 | 30 | ### A simple checklist for reviewers 31 | 32 | Remember that the primary reason for doing code reviews at Open Knowledge Foundation is to distribute knowledge across our team. This does mean identifying areas the code could be improved and asking useful questions, but it does not mean you go too deeply on issues that are clearly subjective. 33 | 34 | Here are some points to hold in mind and guide the review process: 35 | 36 | * What is the context for the code in this pull request (what does the app/library actually do)? 37 | * What is the desired functionality being introduced or fixed? 38 | * Is the code idiomatic for the language and/or framework it is written in? 39 | 40 | There are some clear red flags that, on seeing any of them, you should immediately ask your colleague to address before continuing with any code review: 41 | 42 | * There is no CI 43 | * There are no tests 44 | * There are tests that fail 45 | * There is code that is not linted 46 | 47 | ### Prioritizing code reviews 48 | 49 | Code reviews should take the highest priority of work during the day. When a colleague asks for a review, s/he is asking for work to be validated, and to be unblocked in order to move forward to other tasks. Respect this and address the code review as soon as possible. 50 | 51 | Sometimes, you will be asked to review and you are simply not available (due to meetings or deadlines on the same day - not due to "having your own work to do"). In such cases, communicate immediately with the colleague requesting review so that s/he can find an alternative. 52 | 53 | ### Effort, distraction, and code reviews 54 | 55 | Considering the priority given to code reviews, it could be easy to fall into seeing them as a distraction, or a wasted effort. Try to avoid this way of thinking, and relate to the reasons why we are actually doing code reviews (outlined in "Why") below. 56 | 57 | ### Expertise 58 | 59 | A situation may occur where you are reviewing a language that you do not feel skilled enough in. This does not prevent your ability to review. Ask the developer simple questions, try to understand the general flow. There is an important learning element in this process - languages, techniques, projects, requirements - so lack of familiarity with a language is not a blocker to being a reviewer. 60 | 61 | ### Responsibility 62 | 63 | Reviewers don't hold final responsibility for code - the person who wrote the code does. Reviewing is a best effort endeavour. 64 | 65 | ## Why 66 | 67 | There are many reasons to do code reviews, some technical and some social (in fact, all the reasons are a mix of both). 68 | 69 | Here are the reasons that are important for us to do code reviews at OKI now: 70 | 71 | * We have a diverse team of developers with a wide range of professional experience: code reviews are an avenue for knowledge sharing. 72 | * We have a great number of projects and products, but most of us work in particular areas: code reviews provide visibility and insight into what else is happening with our technical product beyond what any one person directly works on. 73 | * It can be easy to get stuck in patterns when writing code and focused on delivery: code reviews open the possibility for collaborative problem solving. 74 | 75 | --------------------------------------------------------------------------------