From 36c8a103ced361698c5b2c457c5ef932afaab5d4 Mon Sep 17 00:00:00 2001 From: Saransh Chopra Date: Thu, 19 Sep 2024 16:20:05 +0100 Subject: [PATCH] gh-185: update CONTRIBUTING.md (developer guide) --- CONTRIBUTING.md | 176 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 140 insertions(+), 36 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 88b75ffd..d4ad21b9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,143 @@ -# Contributing guidelines +# Contributing to GLASS -## Workflow +If you are planning to develop _GLASS_, or want to use the latest commit of +_GLASS_ on your local machine, you might want to install it from the source. +This installation is not recommended for users who want to use the stable +version of _GLASS_. The page below describes how to build, test, and develop +_GLASS_. + +## Installation + +The developer installation of _GLASS_ comes with several optional dependencies - + +- `test`: installs `scipy`, `fitsio`, and the relevant `pytest` dependencies +- `docs`: installs `sphinx`, `nbsphinx`, and a few other docs related + dependencies +- `examples`: installs `camb`, `glass.ext.camb`, and a few notebook related + dependencies + +These options can be used with `pip` with the editable (`-e`) mode of +installation in the following way - + +```bash +pip install -e .[docs,test] +``` + +## Tooling + +### Pre-commit + +_GLASS_ uses a set of `pre-commit` hooks and the `pre-commit.ci` bot to format, +lint, and prettify the codebase. The hooks can be installed locally using - + +```bash +pre-commit install +``` + +This would run the checks every time a commit is created locally. The checks +will only run on the files modified by that commit, but the checks can be +triggered for all the files using - + +```bash +pre-commit run --all-files +``` + +If you would like to skip the failing checks and push the code for further +discussion, use the `--no-verify` option with `git commit`. + +## Testing + +_GLASS_ is tested using `pytest` and `pytest-doctestplus`. `pytest` is +responsible for testing the code, whose configuration is available in +[pyproject.toml](https://github.com/glass-dev/glass/blob/main/pyproject.toml). +`pytest-doctestplus` is responsible for testing the examples available in every +docstring, which prevents them from going stale. Additionally, _GLASS_ also uses +`pytest-cov` (and [Coveralls](https://coveralls.io)) to calculate/display the +coverage of these unit tests. + +### Running tests locally + +The tests can be executed using the `test` dependencies of _GLASS_ in the +following way - + +```bash +python -m pytest --cov=glass --doctest-plus -v +``` + +## Documenting + +_GLASS_'s documentation is mainly written in the form of +[docstrings](https://peps.python.org/pep-0257) and +[reStructurredText](https://docutils.sourceforge.io/docs/user/rst/quickref.html). +The docstrings include the description, arguments, examples, return values, and +attributes of a class or a function, and the `.rst` files enable us to render +this documentation on _GLASS_'s documentation website. + +_GLASS_ primarily uses [Sphinx](https://www.sphinx-doc.org/en/master/) for +rendering documentation on its website. The configuration file (`conf.py`) for +`sphinx` can be found +[under the `docs` folder](https://github.com/glass-dev/glass/blob/main/docs/conf.py). +The documentation is deployed on [https://readthedocs.io]() +[here](https://glass.readthedocs.io/en/latest/). + +Ideally, with the addition of every new feature to _GLASS_, documentation should +be added using comments, docstrings, and `.rst` files. + +### Building documentation locally + +The documentation is located in the `docs` folder of the main repository. This +documentation can be generated using the `docs` dependencies of _GLASS_ in the +following way - + +```bash +cd docs/ +make clean +make html +``` + +The commands executed above will clean any existing documentation build and +create a new build under the `docs/_build` folder. You can view this build in +any browser by opening the `index.html` file. + +## Releases + +To release a new version of _GLASS_, there should be a commit titled +`REL: glass yyyy.mm` that includes the following changes: + +- The changelog trailers since the last release are parsed into the + [changelog](CHANGELOG.md) under a section titled `[yyyy.mm] (DD Mon YYYY)`. A + new link to the changeset is added at the bottom of the file. +- The [release notes](docs/manual/releases.rst) are updated with the new + version. The release notes should translate the changelog entries into prose + that can be understood by non-developer users of the code. If there are + breaking changes, a release note should explain what the changes mean for + existing code. + +Once these changes are merged into the `main` branch, a new release with title +`glass yyyy.mm` should be created in the GitHub repository. The description of +the release should be a copy of its release note. + +Creating the release will automatically start the build process that uploads +Python packages for the new version to PyPI. + +If any _GLASS_ extension packages depend on the new release, new versions of +these packages should be produced as soon as the new release is published to +PyPI. + +### Versioning + +_GLASS_ follows [CalVer](https://calver.org). There is no difference between +releases that increment the year and releases that increment the month; in +particular, releases that increment the month may introduce breaking changes. +The version is generate dynamically through VCS using `hatch-vcs`. + +The target is to have a new _GLASS_ release at the beginning of each month, as +long as there have been changes. + +The current version number is automatically inferred from the last release (i.e. +git tag), subsequent unreleased commits, and local changes, if any. + +## Contributing workflow Every change to the repository should come out of an issue where the change is discussed. @@ -13,7 +150,7 @@ The discussion in a pull request should only be about the low-level details of its implementation. All high-level, conceptual discussion belongs to the issue to which the pull request refers. -## Pull requests +### Pull requests Pull requests to the `main` branch should have titles of the following form: @@ -52,36 +189,3 @@ You can use any of the other common git trailers. In particular, you can use `Cc` to notify others of your pull request via their GitHub user names: Cc: @octocat - -## Versioning - -The target is to have a new _GLASS_ release at the beginning of each month, as -long as there have been changes. - -The current version number is automatically inferred from the last release (i.e. -git tag), subsequent unreleased commits, and local changes, if any. - -## Releasing - -To release a new version of _GLASS_, there should be a commit titled -`REL: glass yyyy.mm` that includes the following changes: - -- The changelog trailers since the last release are parsed into the - [changelog](CHANGELOG.md) under a section titled `[yyyy.mm] (DD Mon YYYY)`. A - new link to the changeset is added at the bottom of the file. -- The [release notes](docs/manual/releases.rst) are updated with the new - version. The release notes should translate the changelog entries into prose - that can be understood by non-developer users of the code. If there are - breaking changes, a release note should explain what the changes mean for - existing code. - -Once these changes are merged into the `main` branch, a new release with title -`glass yyyy.mm` should be created in the GitHub repository. The description of -the release should be a copy of its release note. - -Creating the release will automatically start the build process that uploads -Python packages for the new version to PyPI. - -If any _GLASS_ extension packages depend on the new release, new versions of -these packages should be produced as soon as the new release is published to -PyPI.