Contributing¶
The SPUX’onic way¶
When contributing, please always make an effort to adhere the SPUX’onic coding style and ethics:
- think (at least) twice about proper variable names:
- avoid abbreviations and slang,
- prioritize descriptive single-word variables to lengthy “sentence”-variables,
- use docstrings for each class and method you implement,
- place technical methods into
spux.utils
orspux.io
, - always use the
verbosity
level filter for any (carefully formatted, of course) output to console, - always clean up (remove debug code and unnecessary comments) before merging to test branch.
Types of contributions¶
You can contribute in many ways, listed in the following paragraphs.
Report bugs¶
Report bugs at https://gitlab.com/siam-sc/spux/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.
Fix bugs¶
Look through the GitLab issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.
Implement features¶
Look through the GitLab issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.
Write documentation¶
SPUX could always benefit from more documentation, whether as part of the official spux docs, in docstrings, or even on the web in blog posts, articles, and such.
To contribute to the official spux docs, checkout the the spux repository
and look through all the files listed in the MANIFEST.in
file.
The auto-generated documentation from all these files is placed under the docs/
directory,
where static files such as plots, tables, etc. are located under docs/_static
(please respect the current directory structure).
When adding your new contributions to the documentation, please follow the current style and make sure that:
- Code snippet uses the code block (instead of a standard paragraph text).
- Code snippet has no remaining programmer comments, notes, or legacy code.
- The line lengths of the code snippet do not protrude beyond the right margin of the paragraph.
Submit feedback¶
The best way to send feedback is to file an issue at https://gitlab.com/siam-sc/spux/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.
- Contributions are very welcome and will make the framework better for you and other users.
Get started!¶
Ready to contribute? Here’s how to set up spux for local development.
Fork the spux repo on GitLab.
Clone your fork locally:
$ git clone git@gitlab.com:siam-sc/spux.git $ cd spux/
(Optional) Install virtualenv and virtualenvwrapper (and source paths, if needed):
$ pip install virtualenvwrapper
(Optional) Install your local copy into a virtualenv:
$ mkvirtualenv spux $ workon spux
Set up your fork for local development (use –user at the end if needed):
$ pip install -r requirements_dev.txt $ python setup.py develop
Create a branch for local development (name it dev_username for private development branch):
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
You can run tests within your environment:
$ flake8 spux tests examples $ pytest -m "not mpi" tests $ mpiexec -n 1 --oversubscribe pytest -m "mpi" tests
Or, alternatively (a slower approach), using tox to include testing with Python and MPI versions:
$ tox
To get flake8 and tox, just pip install them into your virtualenv.
Commit your changes and push your branch to GitLab:
$ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature
Make sure all tests pass in the GitLab-CI as well.
Submit a merge request (e.g. to the “test” branch) through the GitLab website.
Maintainers: review merge request and activate “Merge automatically when pipeline succeeds”.
Merge requests¶
Before you submit a merge request, check that it meets these guidelines:
- The merge request should include tests.
- If the merge 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 merge request should work for Python 3.7.
Tips¶
To run only non-MPI tests:
$ pytest -m "not mpi" tests
or only short module tests, excluding long integration tests:
$ pytest -m "not mpi and not integration" tests
or only long integration tests using MPI:
$ pytest -m "mpi and integration" tests
To run tests from a single file:
$ pytest tests/test_spux.py
or a single test function:
$ pytest tests/test_spux.py::test_imports
To add dependency, edit appropriate
*requirements
variable in thesetup.py
file and re-run:$ python setup.py develop
Check if this requirement should be also included in the
requirements_dev.txt
file.
Deploying¶
A reminder for the maintainers on how to deploy.
- Make sure all issues on GitLab associated with this release milestone are:
- either fixed and closed with changes merged into the
test
branch, - or re-assigned to future release milestones.
- either fixed and closed with changes merged into the
- Review documentation and make sure all examples and statements are up to date:
- run
make docs_html
in the terminal and check generated html pages carefully, - check all source code snippets that use specific line numbers and fix them,
- check if additional examples, results, or publications should be added for the gallery,
- check if additional contributions should be added in the credits.
- run
- Verify all filenames listed in
MANIFEST.in
, including all needed package directories. - Merge the release version of the code to the
release
branch, make sure all tests pass. - Make sure all your changes are COMMITTED (!), including:
- an entry in
HISTORY.rst
, - (optionally) the development status change in
setup.py
(see here for options).
- an entry in
- Make sure you have
texlive-science
,latexmk
, andimage-magick
installed for PDF documentation. - Make sure your working branch is
release
.
Then run in the terminal:
$ pip install -U -r requirements_rtd.txt
$ make docs
$ make clean
$ bumpversion patch # possible: major / minor / patch; might need --allow-dirty
$ git push
$ git push --tags
Afterwards, GitLab-CI will automatically deploy the release to PyPI and ReadTheDocs if tests pass.
Then merge the release
branch into the master
and test
branches.