Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
212 lines (158 loc) · 15.6 KB

CONTRIBUTING.md

File metadata and controls

212 lines (158 loc) · 15.6 KB

Contributing to CLMM

This is a brief guide to contributing to CLMM, including information about identifiying code issues and submitting code changes or documentation.

Table of contents

  1. Identifying Issues
  2. Making and submitting changes
  3. Adding documentation
  4. Reviewing an open pull request
  5. Steps to merging a pull request
  6. Updating Public Documentation on lsstdesc.org
  7. Creating installation via pip and conda
  8. Additional resources
  9. Contact

Identifying Issues

Action items for CLMM code improvements are listed as GitHub Issues. Issues marked with the label good first issue are well-suited for new contributors.

Making and submitting changes

Once you've created a local copy of CLMM on your machine, you can begin making changes to the code and submitting them for review. To do this, follow the following steps from within your local copy of CLMM (forked or base).

  1. Checkout a new branch to contain your code changes independently from the main repository. Branches allow you to isolate temporary development work without permanently affecting code in the repository. 
    git checkout -b branchname
    Your branchname should be descriptive of your code changes. If you are addressing a particular issue #xx, then branchname should be formatted as issue/xx/summary where summary is a description of your changes.
  2. Make your changes in the files stored in your local directory.
  3. Commit and push your changes to the branchname branch of the remote repository. 
    git add NAMES-OF-CHANGED-FILES
git commit -m "Insert a descriptive commit message here"
git pull origin main
git push origin branchname
  4. You can continue to edit your code and push changes to the branchname remote branch. Once you are satisfied with your changes, you can submit a pull request to merge your changes from branchname into the main branch. Navigate to the CLMM Pull Requests and click 'New pull request.' Select branchname, fill out a title and description for the pull request, and, optionally, request review by a CLMM team member. Use the template provided for a pull request, it will faciliate the process for everybody. Once the pull request is approved, it will be merged into the CLMM main branch.

Requirements for every change

We want to make sure the code formatting in CLMM is standardized accordind to our guidelines, which facilitates the reading of the code. The code is also not complete without unit tests and documentation. Please ensure that unit tests (both new and old) all pass and that docs compile successfully. So remember these steps:

  • Formatting the code: there are tools that will format the code automatically for you, so you don't have to worry about the correct syntax when developing it. Once you add your changes, black clmm/ and isort clmm/ before you commit your changes. These tools will correctly format the spacing and importing order respectilely. Tip: black can also be run on notebooks, just install the notebook extention: pip install "black[jupyter]".

  • Structuring the code: Run pylint clmm/, this will produce a diagnostic about the implementation and tell you what needs to be improved.

  • Reinstall CLMM: After your changes, resinstall CLMM by running pip install . (required after any change whatsoever to the .py files in clmm/ directory). This will ensure your implementation is being used in the tests and documentation. Developer tip: You can install CLMM in a editable mode, where the latest files on the repo will always be used, with the command pip install . -e. In this case you will not have to reinstall it at every change.

  • Unit tests: To run all of the unit tests, run pytest in the root package directory.

  • Coverage: Check the coverage of the code, i. e. how many lines of the code are being tested in our unittests. To do it locally, you need the pytest-cov library (it can be insatalled with pip). Then run the command pytest tests/ --cov=clmm --cov-report term-missing, it will tell you what fraction of the code is being tested and which lines are not being tested.

  • Notebooks: Make sure all notebooks can run correctly. We provide a convenient bash script to compile the documentation, run ./run_notebooks in the main CLMM directory. It will create an executed version of all notebooks in the _executed_nbs/ directory. By default it uses a python3 kernel, if you want to choose another one, just pass it to the command: ./run_notebooks -k MY_KERNEL. (Note that depending on your theory backend, some cells in some notebooks will give an error. This expected behaviour is explicitely mentioned before the cells and should not be a cause of worry.)

  • Build the documentation: To test the docs, in the root package directory after installing, run ./update_docs. This script both deletes the old compiled documentation files and rebuilds them. You can view the compiled docs by running open docs/_build/html/index.html.

NOTE: If the changes you are making affect which CCL or NumCosmo versions are compatible with the code, please update clmm/theory/_ccl_supported_versions.py, environment.yml, README.md and INSTALL.md accordingly. Also, any changes on the constraints on CLMM dependencies should be reflected on environment.yml and pyproject.toml. It is also necessary to update those constraints on conda-forge after a specific release. Please notify the maintainers if that's necessary.

All these steps (except running the notebooks) are run automatically on each pull request on GitHub, so you will know if any of them require further attention before considering youre changes are ready to be reviewed. Check details on Build and Check / build-gcc-ubuntu (pull_request) section at the end of the PR and coverage under the coveralls comment in the middle of the PR.

Adding documentation

If you are adding documentation either in the form of example jupyter notebooks or new python modules, your documentation will need to compile for our online documentation hosted by the LSST-DESC website: http://lsstdesc.org/CLMM/

We have done most of the hard work for you. Simply edit the configuration file, docs/doc-config.ini. If you are looking at add a module, put the module name under the APIDOC heading. If you are adding a demo notebook to demonstrate how to use the code, place the path from the docs/ directory to the notebook under the DEMO heading. If you are adding an example notebook that shows off how to use CLMM to do science, place the path from the docs/ directory to the notebook under the EXAMPLE heading.

Once it has been added to the config file, simply run ./update_docs from the top level directory of the repository and your documentation should compile and be linked in the correct places!

Reviewing an open pull request

To review an open pull request submitted by another developer, there are several steps that you should take.

  1. Code changes: For each new or changed file, ensure that the changes are correct, well-documented, and easy to follow. If you notice anything that can be improved, leave an inline comment (click the line of code in the review interface on Github).

  2. Documentation: Double check any relevant documentation. For any new or changed code, ensure that the documentation is accurate (i.e. references, equations, parameter descriptions).

  3. Check unittests: For any new or changed code, ensure that there are new tests in the appropriate directory. Try to come up with additional tests that either do or can break the code. If you can think of any such tests, suggest adding them in your review.

  4. Tests for formatting, documentation and unit tests: The CI runs automatically tests for code formatting, documentation and unit tests, so the checks will fail if there are any problems. To see how to perform these steps manually, check the Requirements for every change section.

  5. Notebooks: Make sure all notebooks can run correctly as this is not run by the CI, check Requirements for every change for details.

  6. Documentation: Check that the documentation looks as it should, see Requirements for every change for details.

Steps to merging a pull request

To ensure consistency between our code and documentation, we need to take care of a couple of more things after accepting a review on a PR into main.

  1. In the branch of the pull request, change the version number of the code located in clmm/__init__.py, commit and push. If you are unsure of how you should change the version number, don't hesitate to ask!

We use semantic versioning, X.Y.Z. If the PR makes a small change, such as a bug fix, documentation updates, style changes, etc., increment Z. If the PR adds a new feature, such as adding support for a new profile, increment Y (and reset Z to 0). If a PR adds a feature or makes a change that breaks the old API, increment X (and reset Y and Z to 0). After the first tagged release of CLMM, anything that is a candidate to increment X should be extensively discussed beforehand.

  1. "Squash and Merge" the pull request into main. It asks for a squashed commit message. This should be descriptive of the feature or bug resolved in the PR and should be pre-prended by a conventional commit scope.

Please choose from fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test:. If this commit breaks the previous API, add an explanation mark (for example, fix!:). Definitions of each scope can be found at the above link.

Note: fix: should correspond to version changes to Y. The rest of the scopes above should be version changes to Z.

  1. Tag and push this new version of the code. In the main branch use the following commands:

    git tag X.Y.Z
git push --tag

of course replacing X.Y.Z by the new version.

Updating Public Documentation on lsstdesc.org

This is easy! Once you have merged all approved changes into main, you will want to update the public documentation. All these steps should be done on the publish-docs branch (just git checkout publish-docs on your local computer):

  1. Merge all of the latest changes from main git merge main.
  2. If you have figures in notebooks that you would like rendered on the website, you will want to execute all cells of demo notebooks.
  3. From the main CLMM directory (the one that contains setup.py) run ./publish_docs (note, this is different from ./update_docs that you did in your development branch) and it does all of the work for you (including automatically pushing changes to Github)!

Creating installation via pip and conda

PyPI and conda-forge publishing can be done automatically by creating a new release on the repository, and the developer usually won't have to worry about this issue. However, if necessary, it is also possible to manually perform this process. Intructions below:

Manual publication to `PyPI` and `conda-forge`
  1. Build the needed files for publication with the command: 
    hatch build

This will create a clmm-1.14.4.tar.gz and clmm-1.14.4-py3-none-any.whl files in the dist folder inside the repository. Note that the name of the files will change for the given version to be publicated. 2. To publish the package to pip, we will use twine, which should be installed with the following: bash pip install twine

  1. To make sure that the package is working properly, we can first publish clmm to PyPITest running the command: 
    twine upload --repository testpypi dist/* --verbose

Once the package is published, one can install it by running: bash pip install -i https://test.pypi.org/simple/ clmm==1.14.4 --extra-index-url https://pypi.org/simple clmm==1.14.4 with the proper version number. This step will require an account at PyPITest and you will need to generate a token that is required to publish packages. Note that some of the required dependencies may note be published to PyPITest and thus we need the extra index url to import the packages from PyPI. If the package was properly installed, we are now ready to publish it to PyPI.

  1. To publish to PyPI, run the command:
twine upload dist/*

This last step must be done with the token used to publish CLMM from the right account at PyPI. Once this is done, you will find the latest version of CLMM at the PyPI repository. To test it, try running

pip install clmm
  1. The package published to PyPI will then automatically be picked up by conda-forge and published on that repository.

Additional resources

Here's a list of additional resources which you may find helpful in navigating git for the first time.

Contact (alphabetical order)

The current administrators of the repository are Michel Aguena and Céline Combet.