Contributing¶

eTraGo is a collaborative project with several people contributing to it. The following section gives an overview of applicable guidelines and rules to enable a prospering collaboration. Any external contributions are welcome as well, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Bug Reports and Feature Requests¶

The best way to report bugs, inform about intended developments, send feedback or propose a feature is to file an issue at: https://github.com/openego/eTraGo/issues

Please tag your issue with one of the predefined labels as it helps others to keep track of unsolved bugs, open tasks and questions.

To inform others about intended developments please include:

a description of the purpose and the value it adds
outline the required steps for implementation
list open questions

When reporting a bug please include all information needed to reproduce the bug you found. This may include information on:

your operating system name and version
any details about your local setup that might be helpful in troubleshooting
detailed steps to reproduce the bug

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.

Contribution Guidelines¶

General Procedure¶

Adding changes to the eTraGo repository should follow some guidelines:

Create an issue in our repository to briefly describe the intended developments.
Create a branch for your issue-related development from the dev branch following our branch naming convention:
```
git checkout -b <prefix>/#<issue-id>-very-brief-description
```
where issue-id is the issue number on GitHub and prefix is one of:
- features
- fixes
- refactorings
depending on which one is appropriate. This command creates a new branch in your local repository, in which you can now make your changes. Be sure to check out our style conventions so that your code follows them.

If you don’t have push rights to our repository, you need to fork it via the “Fork” button in the upper right corner of the repository page and work on your fork.
Make sure to update the documentation along with your code changes. Therefore, please check out the documentation guidelines.

When adding new package imports to a script, ensure that all internal eTraGo modules are imported during the Read the Docs build process. All external packages should be imported above the conditional if statement.
When you’re done making changes, run all checks and build the docs using tox with one command:
```
tox
```
Commit your changes and push your branch to GitHub:
```
git add -p
git commit
git push origin features/#<issue-id>-very-brief-description
```
Note that the -p switch will make git add iterate through your changes and prompt for each one on whether you want to include it in the upcoming commit. This is useful if you made multiple changes which should conceptually be grouped into different commits (e.g., fixing the documentation of one function and changing the implementation of an unrelated one in parallel). It has the drawback of not picking up new files, so if you added files and want to put them under version control, you have to add them explicitly by running git add FILE1 FILE2 ....
Submit a pull request through the GitHub website.

Within the pull request, please refer to the corresponding issue and briefly explain how the reviewers can, from your perspective, verify your changes. Please check out the corresponding Documentation guidelines.

Code and Commit Style¶

We try the adhere to the PEP 8 Style Guide wherever possible. In addition to that, we use a code formatter to have a consistent style, even in cases where PEP 8 leaves multiple degrees of freedom. So please run your code through black before committing it. [1] PEP 8 also specifies a way to group imports, onto which we put the additional constraint that the imports within each group are ordered alphabetically. Once again, you don’t have to keep track of this manually, but you can use isort to have imports sorted automatically.

Unfortunately these tools don’t catch everything, so here’s a short list of things you have to keep track of manually:

black can’t automatically break up overly long strings, so make use of Python’s automatic string concatenation feature by e.g. converting
something = "A really really long string"
into the equivalent:
something = (
    "A really really"
    " long string"
)
black also can’t check whether you’re using readable names for your variables. So please don’t use abbreviations. Use readable names.

black also can’t reformat your comments. So please keep in mind that PEP 8 specifies a line length of 72 for free flowing text like comments and docstrings. This also extends to the documentation in reStructuredText files.

Last but not least, commit messages are a kind of documentation, too, which should adhere to a certain style. There are quite a few documents detailing this style, but the shortest and easiest to find is probably https://commit.style. If you have 15 minutes instead of only five to spare, there’s also a very good and only slightly longer article on this subject, containing references to other style guides, and also explaining why commit messages are important.

At the very least, try to only commit small, related changes. If you have to use an “and” when trying to summarize your changes, they should probably be grouped into separate commits.

Pull Request Guidelines¶

We use pull requests (PR) to integrate code changes from branches. PRs always need to be reviewed (exception proves the rule!). Therefore, ask one of the other developers for reviewing your changes. Once approved, the PR can be merged. Please delete the branch after merging.

When requesting reviews, please keep in mind it might be a significant effort to review the PR. Try to make it as easy as possible for the reviewer(s) and keep the overall effort as low as possible.

Asking for reviewing specific aspects helps reviewers a lot to focus on the relevant parts.
When multiple people are requested for a review, try to avoid having them check or test the same aspects. Be as specific as possible about what you expect from each reviewer.

Documentation¶

eTraGo could always use more documentation, whether as part of the official eTraGo docs, in docstrings, or even in articles, blog posts or similar resources. Always keep in mind to update the documentation along with your code changes though.

The changes of the documentation in a feature branch get visible once a pull request is opened.

How to document Python Scripts¶

Use docstrings to document your Python code. Note that PEP 8 also contains a section on docstrings and that there is a whole PEP dedicated to docstring conventions. Try to adhere to both of them. Additionally, every Python script needs to contain a header describing the general functionality and objective and including information on copyright, license and authors.

""" Provide an example of the first line of a module docstring.

This is an example header describing the functionalities of a Python
script to give the user a general overview of what's happening here.
"""

__copyright__ = "Example Institut"
__license__ = "GNU Affero General Public License Version 3 (AGPL-3.0)"
__url__ = "https://github.com/openego/eTraGo/blob/main/LICENSE"
__author__ = "github_alias1, github_alias2"

You can build the documentation locally by executing the following code in the repos root directory:

sphinx-build -E -a docs docs/_build/

Eventually, you need to install additional dependencies for building the documenmtation:

pip install -r docs/requirements.txt