Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
Types of Contributions¶
Report bugs at https://github.com/esm-tools/esm_tools/issues.
If you are reporting a bug, please include:
Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.
Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.
Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.
ESM Tools could always use more documentation, whether as part of the official ESM Tools docs, in docstrings, or even on the web in blog posts, articles, and such.
The best way to send feedback is to file an issue at https://github.com/esm-tools/esm_tools/issues.
If you are proposing a feature:
Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)
Ready to contribute? Here’s how to set up esm-tools packages for local development (see Python Packages for a list of available packages). Note that the procedure of contributing to the esm_tools package (see Contribution to esm_tools Package) is different from the one to contribute to the other packages (Contribution to Other Packages).
Contribution to esm_tools Package¶
Fork the esm_tools repo on GitHub.
Clone your fork locally:
$ git clone https://github.com/esm-tools/esm_tools.git
(or whatever subproject you want to contribute to).
git clonewill give you the release branch of the project. You might want to consider checking out the development branch, which might not always be as stable, but usually more up-to-date than the release branch:
$ git checkout develop
Create a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
When you’re done making changes, check that your changes pass flake8:
$ flake8 esm_tools
Commit your changes and push your branch to GitHub:
$ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature
Submit a pull request through the GitHub website.
Contribution to Other Packages¶
Follow steps 1-4 in Contribution to esm_tools Package for the desired package, cloning your fork locally with:
$ git clone https://github.com/esm-tools/<PACKAGE>.git
Proceed to do a development install of the package in the package’s folder:
$ cd <package's_folder> $ pip install -e .
From now on when binaries are called, they will refer to the source code you are working on, located in your local package’s folder. For example, if you are editing the package esm_master located in
~/esm_masterand you run
$ esm_master install-fesom-2.0you’ll be using the edited files in
~/esm_masterto install FESOM 2.0.
Follow steps 5-7 in Contribution to esm_tools Package.
Get Back to the Standard Distribution¶
Once finished with the contribution, you might want to get back to the standard
non-editable mode version of the package in the
release branch. To do that
please follow these steps:
Uninstall all ESM-Tools packages (Uninstall ESM-Tools). This will not remove the folder where you installed the package in editable mode, just delete the links to that folder.
Navigate to the
esm_toolsfolder and run the
Check that your package is now installed in the folder
If the package is still shows the path to the editable-mode folder, try
pip install --use-feature=in-tree-build . from
Pull Request Guidelines¶
Before you submit a pull request, check that it meets these guidelines:
The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
The pull request should work for Python 3.5, 3.6, 3.7 and 3.8, and for PyPy. Check https://travis-ci.com/dbarbi/esm_tools/pull_requests and make sure that the tests pass for all supported Python versions.
A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in HISTORY.rst). Then run:
$ bumpversion patch # possible: major / minor / patch $ git push $ git push --tags