PyRC’s Contributing Guidelines#

You can support the PyRC project in many different ways. Because of the early state of PyRC, even small contributions make a significant difference — you do not need to implement large or complex features to help. Just think about to do one of the following:

Add and improve docstrings
Report bugs or suggest features by opening an issue
Write or extend tests
Fix bugs (see open issues)
Improve documentation

Currently, the test coverage is not the best. So a big help would be to write some tests for existing code.

Development Process — Summary#

The following is a short summary of the contribution workflow.

If you are a first-time contributor#

Go to the PyRC repository on Codeberg and click Fork to create your own copy of the repository under your personal account.

Clone your fork to your local machine:

git clone https://codeberg.org/<your-username>/pyrc.git
cd pyrc

Add the upstream repository:
```
git remote add upstream https://codeberg.org/IGTE/pyrc.git
```
Running git remote -v should now show two remotes:
- origin — your personal fork
- upstream — the official PyRC repository

Keep your fork up to date before starting work:

git checkout main
git pull upstream main --tags

Build the environment#

Create the virtual environment and activate it. Run following commands from your project folder:
```
python -m venv .venv
```

Activate the environment on Windows or Linux:

.venv\Scripts\activate    # Windows
source .venv/bin/activate # Linux

Install all packages, including the ones for development and documentation:
```
pip install -e ".[dev,docs]"
```
(Optional) Check, if everything works by running tests:
```
pytest
```

Develop your contribution#

Create a branch with a sensible name reflecting the change, prefixed by its type:
```
git checkout -b fix/issue-42 # or
git checkout -b feature/add-something # or
git checkout -b docs/improve-readme
```
Branch prefixes:
- fix/ — bug fixes, referencing the issue number if applicable
- feature/ — new functionality
- docs/ — documentation only changes
Make your changes. Commit locally as you progress:
```
git add .
git commit -m "Short descriptive message, closes #42"
```
Commit message conventions:
- Use the imperative mood: Add feature, not Added feature
- Reference issues with closes #<number> or refs #<number>
Run the tests before pushing:
```
pytest
```

Submit your contribution#

Push your branch to your fork:

git push origin <your-branch-name> # branch name example: fix/issue-42

Open a Pull Request (PR) on Codeberg from your branch into main of the upstream repository.
In the PR description:
- Summarize what the PR does and why
- Reference the related issue with Closes #<number>
- List any open questions or known limitations
- Add an AI usage disclosure like described in AI Policy
  
  Example AI Disclosure for Pull Request
  
  AI Disclosure: I used the web service of claude.ai to generate a first draw of the contributing.rst file and edited and updated this draw until it matched my expectations. Also, I used deepl.com to translate some German text into English for documentation and docstrings and to improve my writing style. I read and understand any code and text and would have written it in the same way.

Further contributions#

When you want to contribute further using the same fork you can update your local file.

(Optional) When your Pull Request was already accepted and merged into main: Delete the old branch locally and remote:
```
git branch -d <your-branch-name>
git push origin --delete <your-branch-name>
```
Synchronize your main branch with the upstream main branch:
```
git checkout main
git pull upstream main --tags
```
Push the changes to your remote fork repository:
```
git push origin main
```

Now you are ready to create a new branch locally, make changes, push it, create a Pull Request and repeat :)

Review process#

At least one maintainer must approve the PR before it can be merged.
Address review comments by pushing additional commits to the same branch — the PR updates automatically.
Once approved, a maintainer will merge the PR. Your feature branch will be deleted automatically after merging.

Guidelines#

Code style#

Follow PEP 8.
Do not use abbreviations.
Use NumPy docstring format for all public functions, classes, and methods.
Use double quotes for strings and a maximum line width of 120.
Use SI units. Only exceptions are functions for plotting, where you can name parameters like: height_mm

Maintain code together

If everyone leaves the code in better shape than they found it, the code will maintain itself.

Yes, some of the code won’t follow the coding style, but there’s no need to get upset about it. It’s enough to improve the style a little.

Tests#

All new code must be accompanied by tests.
Tests are located in pyrc/tests/ and use unittest.
Run the full test suite with:
```
pytest
```
Aim for full statement coverage of any module you modify. Check coverage in docs/build/html/coverage/index.html:
```
pytest --cov=pyrc --cov-report=html:docs/build/html/coverage
```

Documentation#

The documentation is auto-generated using Sphinx and autodoc. It will parse all docstrings into html pages that are published under pyrc.de.

All public API must have a NumPy-style docstring.
If your change modifies user-facing behaviour, update the documentation accordingly.

Currently, building the documentation is only tested using Windows. From the project folder (same level as pyrc folder) run:

.\docs\build_new.bat

This will delete most of all rst files (if existing) in ./docs/source except manually maintained ones. Then autodoc and sphinx create the rst-files for every PyRC-module and build html pages. Show the documentation by opening /docs/build/html/index.html in your browser.

Versioning and changelog#

PyRC follows Semantic Versioning (MAJOR.MINOR.PATCH).
If your change affects the public API or user-facing behaviour, add an entry to CHANGELOG.rst in the Unpublished section.

More information#

Contents:

AI Policy