Contributing to f90nml
¶
f90nml
development is driven by user feedback, and your contributions help
to find bugs, add features, and improve performance. This is a small guide to
help those who wish to contribute.
Development Portal¶
Code development is currently hosted at GitHub. Issues, feature requests, and code contributions are currently handled there.
Reporting errors¶
Any errors or general problems can be reported on GitHub's Issue tracker:
The quickest way resolve a problem is to go through the following steps:
Have I tested this on the latest GitHub (
main
) version?Have I provided a sample code block which reproduces the error? Have I tested the code block?
Have I included the necessary input or output files?
Sometimes a file attachment is required, since uncommon whitespace or Unicode characters may be missing from a cut-and-paste of the file.
Have I provided a backtrace from the error?
Usually this is enough information to reproduce and resolve the problem. In some cases, we may need more information about your system, including the following:
Your
f90nml
version:>>> import f90nml >>> f90nml.__version__ '1.1'
The version and build of python:
>>> import sys >>> print(sys.version) 3.6.8 (default, Apr 25 2019, 21:02:35) [GCC 4.8.5 20150623 (Red Hat 4.8.5-36)]
Your operating system (Linux, OS X, Windows, etc.), and your distribution if relevant.
While more information can help, the most important step is to report the problem, and any missing information can be provided over the course of the discussion.
Feature requests¶
Feature requests are welcome, and can be submitted as Issues in the GitHub tracker.
When preparing a feature request, consider providing the following information:
What problem is this feature trying to solve?
Is it solvable using Python intrinsics? How is it currently handled in similar modules?
Does the feature currently exist in similar modules (JSON, YAML, etc.)?
Can you provide an example code block demonstrating the feature?
For
Namelist
changes, is it compatible with thedict
parent class?Does this feature require any new dependencies (e.g. NumPy)?
As a self-supported project, time is often limited and feature requests are often a lower priority than bug fixes or ongoing work, but a strong case can help to prioritize feature development.
Contributing to f90nml¶
Fixes and features are very welcome to f90nml
, and are greatly encouraged.
Much of the functionality of the Parser
and Namelist
classes have been
either requested or contributed by other users.
If you are concerned that a project may not be suitable or may conflict with ongoing work, then feel free to submit a feature request with comment noting that you are willing to provide the feature.
Feature should be sent as pull requests via GitHub, specifically to the
main
branch, which acts as the main development branch.
Explicit patches via email are also welcome.
When preparing a pull request, consider the following advice:
Commit logs should be long-form. Don't use
commit -m "Added a feature!"
; instead provide a multiline description of your changes.Single line commits are acceptable for very minor changes, such as whitespace.
Commit messages should generally try to be standalone and ought to avoid references to explicit GitHub content, such as issue numbers or usernames.
Code changes must pass existing tests:
$ python setup.py test
Code changes ought to satisfy PEP8, including line length limit. The following should raise no warnings:
$ pycodestyle f90nml
pycodestyle
is available on PyPI via pip:$ pip install pycodestyle
Providing a test case for your example would be greatly appreciated. See
tests/test_f90nml.py
for examples.Features should generally only depend on the standard library. Any features requiring an external dependency should only be enabled when the dependency is available.
In practice, contributions are rare and it's not difficult to sort out these issues inside of the pull request.
Have Fun¶
Most importantly, remember that it is more important to contribute than to follow the rules and never contribute. Issues can be sorted out in real time, and everything can be amended in the world of software.