Developer guidelines

Från Wikimedia
(Omdirigerad från Development guidelines)
Hoppa till navigering Hoppa till sök

Denna sida är på engelska av transparensskäl samt då den använda terminologin oftast är på engelska. Undersidor kan ibland vara på svenska.

The default language for new projects should, whenever appropriate, be Python 3. When compatible the MIT license should be used.

What to include

Log files should not be included in the repositories. When relevant, these may instead be uploaded as attachments to Phabricator tasks.

Input data may be included in the repository depending on scope. E.g. a .json file containing a mapping of parish names to Wikidata may be appropriate whereas all of the metadata for a batch upload may not be. If needed, such files can instead be stored on Nextcloud.

Processed data which can be recreated by re-running the code should never be part of a repository. Output that is expensive to recreate, doesn't take too much space and may be useful in the future van be stored on Nextcloud.

Documentation

Documentation ensures the code is understandable by other members of the team, an external audience, as well as by the coder themselves a year later.

All new public functions and classes are expected to be documented. It is recommended to also document function parameters. A style for parameter documentation has not yet been selected. Python documentation is expected to follow PEP 257.

Code-style and linting

Linting ensures code consistency and reduces the need for nitpicking during code-review. Basic linting is expected to have been done by the person responsible for a PR. Even better is to have linting be part of the CI process. For python, the code style is expected to follow PEP8. Helpful tools are flake8 and pydocstyle.

Gerrit, Github and Phabricator

For MediaWiki development gerrit should always be used. For other projects, Github may often be more appropriate. For one-use-only repositories (such as code for a specific batch upload) Github is recommended. Repositories in Github can either be under the user account or the Wikimedia-Sverige account.

In order to comply with our Phabricator guidelines, issue tracking for any new repositories must be done in Phabricator. To connect the two, Github commit messages should include a link to the Phabricator task, and the commit/Pull request should be linked to from the task. If the patch is up for review the #patch-for-review tag should also be added to the task. To make the issue handling system discoverable, a link to the relevant Phabricator board/project should be added to the README file. It may also be advisable to disable issues in that repository (Settings → Options → Features).

For existing repositories already containing Github issues: new issues should instead be filed as Phabricator tasks. Existing issues should get an equivalent Phabricator task when work commences on them (or if they are included in planning). When created, it should be clear from the task, which the old issue was and from the issue, which task that is now dealing with it.

For repositories which are temporary forks of another Github repository or where there is extensive collaboration outside of Wikimedia, issue tracking may continue in Github.

Code-review and task branching

The implementation of code-review varies between our different projects, but the following are general recommendations.

To make code-review possible, and to keep the commit history cleaner, tasks should be developed in separate branches. These are then merged into the master branch via a gerrit review or a Github pull request (both hereafter PR). The scope of a branch often corresponds to a single Phabricator task (e.g. new functionality, changed functionality, a bug). When merged into master, it is most often appropriate to squash each PR into a single commit.

Whenever possible, PRs should be independent of each other. This way they can be developed in parallel and the review/merge of one is less likely to impact the other.

Code-review happens either on the PR level or, in special cases, before deployment. Unless otherwise decided the review is done by the project manager/senior developer.

Testing

Testing makes it easier to update existing code, to deal with edge cases and to deploy with confidence. It can also help when writing the product code, as it makes you think more about what it does and how.

Unit testing should be implemented in new code. It is not necessary to introduce in older code that's assumed to be working. While not necessary, it may be a good idea to use test driven development.

Integration testing is not required at this point. This can partially be mitigated using documentation in e.g. Phabricator describing the expected output/behaviour given some real-life input examples.

Tests should ideally be run as part of the CI process.

Sub-pages