diff --git a/developer_guideline.md b/developer_guideline.md new file mode 100644 index 00000000..6d4e6d5a --- /dev/null +++ b/developer_guideline.md @@ -0,0 +1,200 @@ +Developer Guideline +=================== + +Here we provide some details about guideline for internal developers. Most of the +choices are explained in the [guide](https://guide.esciencecenter.nl). + +For a quick reference on software development, we refer to [the software +guide checklist](https://guide.esciencecenter.nl/best_practices/checklist.html). + +Version control +--------------- + +We use [git](http://git-scm.com/) and [github](https://github.com/) for developing +[DeepRank](https://github.com/DeepRank/deeprank). And [Github Desktop](https://desktop.github.com/) is recommennded to simplify development workflow. + +To get onboard, first ask project manager to get access to the DeepRank repo (short for repository), then clone the repo to your local machine. + +**The development workflow is as the following**: +1. Create an issue in [the repo Issues](https://github.com/DeepRank/deeprank/issues) for any idea, bug, feature, improvement, etc. +2. Comment and mention (i.e. @) someone in the issue for discussion if necessary. +3. Assign the issue to yourself or someone after asking +4. Create a new branch from the `dev` branch for this issue, and name it in a format of `issue{ID}_*`, e.g. `issue7_format_docstring`. +5. Work in this issue branch to solve the issue. Check this [guide](https://google.github.io/eng-practices/review/developer/) to see how to make good commits. +6. Pull request to merge this issue branch to the `dev` branch when last step is completed. +7. Assign someone but not yourself to review the pull request. For reviewers, check this [guide](https://google.github.io/eng-practices/review/reviewer/) to see how to do a code review. +8. Follow reviewer's comments to fix the code until reviewer approve you to merge. Check this [guide](https://google.github.io/eng-practices/review/developer/handling-comments.html) to see how to handle reviewer comments. +9. Merge the issue branch to `dev` branch and delete the issue branch. +10. Close the issue after leavning a comment of the related pull request ID. + +Repeat the 1-10 steps for next issue. + +Note that try to keep the issue and pull request small for efficient code review. In principle, it should take ≤30 mins to review a pull request. + + +Package management and dependencies +----------------------------------- + +You can use either `pip` or `conda` for +installing dependencies and package management. This repository does not +force you to use one or the other, as project requirements differ. For +advice on what to use, please check [the relevant section of the +guide](https://guide.esciencecenter.nl/best_practices/language_guides/python.html#dependencies-and-package-management). + +- Dependencies should be added to `setup.py` in the + `install_requires` list. + +Packaging/One command install +----------------------------- + +You can distribute your code using pipy or conda. Again, the project +template does not enforce the use of either one. [The +guide](https://guide.esciencecenter.nl/best_practices/language_guides/python.html#building-and-packaging-code) +can help you decide which tool to use for packaging. + +If you decide to use pypi for distributing you code, you can configure +travis to upload to pypi when you make a release. If you specified your +pypi user name during generation of this package, the `.travis.yml` file +contains a section that looks like: + +``` {.sourceCode .yaml} +deploy: + provider: pypi + user: no + password: + secure: FIXME; see README for more info + on: + tags: true + branch: master +``` + +Before this actually works, you need to add an encrypted password for +your pypi account. The [travis +documentation](https://docs.travis-ci.com/user/deployment/pypi/) +specifies how to do this. + +Testing and code coverage +------------------------- + +- Tests should be put in the `test` folder. +- The `test` folder contains: + - Example tests that you should replace with your own meaningful + tests (file: `test_learn.py`) +- The testing framework used is [PyTest](https://pytest.org) + - [PyTest + introduction](http://pythontesting.net/framework/pytest/pytest-introduction/) +- Tests can be run with `python setup.py test` + - This is configured in `setup.py` and `setup.cfg` +- Use [Travis CI](https://travis-ci.com/) to automatically run tests + and to test using multiple Python versions + - Configuration can be found in `.travis.yml` + - [Getting started with Travis + CI](https://docs.travis-ci.com/user/getting-started/) +- TODO: add something about code quality/coverage tool? +- [Relevant section in the + guide](https://guide.esciencecenter.nl/best_practices/language_guides/python.html#testing) + +Documentation +------------- + +- Documentation should be put in the `docs` folder. The contents have + been generated using `sphinx-quickstart` (Sphinx version 1.6.5). +- We recommend writing the documentation using Restructured Text + (reST) and Google style docstrings. + - [Restructured Text (reST) and Sphinx + CheatSheet](http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html) + - [Google style docstring + examples](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). +- The documentation is set up with the Read the Docs Sphinx Theme. + - Check out the [configuration + options](https://sphinx-rtd-theme.readthedocs.io/en/latest/). +- To generate html documentation run `python setup.py build_sphinx` + - This is configured in `setup.cfg` + - Alternatively, run `make html` in the `docs` folder. +- The `docs/_templates` directory contains an (empty) `.gitignore` + file, to be able to add it to the repository. This file can be + safely removed (or you can just leave it there). +- To put the documentation on [Read the + Docs](https://readthedocs.org), log in to your Read the Docs + account, and import the repository (under 'My Projects'). + - Include the link to the documentation in this [README](https://guide.esciencecenter.nl/best_practices/language_guides/python.html#writingdocumentation). +- [Relevant section in the + guide](https://guide.esciencecenter.nl/best_practices/language_guides/python.html#writingdocumentation) + +Coding style conventions and code quality +----------------------------------------- + +- Check your code style with `prospector` +- You may need run `pip install .[dev]` first, to install the required + dependencies +- You can use `autopep8` to fix the readability of your code style and + `isort` to format and group your imports +- [Relevant section in the + guide](https://guide.esciencecenter.nl/best_practices/language_guides/python.html#coding-style-conventions) + +Package version number +---------------------- + +- We recommend using [semantic + versioning](https://guide.esciencecenter.nl/best_practices/releases.html#semantic-versioning). +- For convenience, the package version is stored in a single place: + `deeprank/__version__.py`. For updating the + version number, you only have to change this file. +- Don't forget to update the version number before [making a + release](https://guide.esciencecenter.nl/best_practices/releases.html)! + +Logging +------- + +- We recommend using the `logging` module for getting + useful information from your module (instead of using + `print`). +- The project is set up with a logging example. +- [Relevant section in the + guide](https://guide.esciencecenter.nl/best_practices/language_guides/python.html#logging) + +CHANGELOG.rst +------------- + +- Document changes to your software package +- [Relevant section in the + guide](https://guide.esciencecenter.nl/software/releases.html#changelogmd) + +CITATION.cff +------------ + +- To allow others to cite your software, add a `CITATION.cff` file +- It only makes sense to do this once there is something to cite + (e.g., a software release with a DOI). +- Follow the [making software + citable](https://guide.esciencecenter.nl/citable_software/making_software_citable.html) + section in the guide. + +CODE_OF_CONDUCT.rst +--------------------- + +- Information about how to behave professionally +- [Relevant section in the + guide](https://guide.esciencecenter.nl/software/documentation.html#code-of-conduct) + +CONTRIBUTING.rst +---------------- + +- Information about how to contribute to this software package +- [Relevant section in the + guide](https://guide.esciencecenter.nl/software/documentation.html#contribution-guidelines) + +MANIFEST.in +----------- + +- List non-Python files that should be included in a source + distribution +- [Relevant section in the + guide](https://guide.esciencecenter.nl/best_practices/language_guides/python.html#building-and-packaging-code) + +NOTICE +------ + +- List of attributions of this project and Apache-license dependencies +- [Relevant section in the + guide](https://guide.esciencecenter.nl/best_practices/licensing.html#notice)