Skip to content

Latest commit

 

History

History
226 lines (162 loc) · 7.01 KB

CONTRIBUTING.md

File metadata and controls

226 lines (162 loc) · 7.01 KB
Raw

Contributing

Contributions are welcome, and they are greatly appreciated! Every little helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs to our issue page. 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 GitHub issues for bugs. Anything tagged with "bug" and "help wanted" is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with "enhancement" and "help wanted" is open to whoever wants to implement it.

Write Documentation

The ZDS slide set material could always use more documentation and content, whether as part of the official documentation, in reStructuredText, or even on the web in blog posts, articles, and such.

Further readings for you as new contributor:

Submit Feedback

The best way to send feedback our issue page on GitHub. 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 😊

System Requirements

The ideal development environment is a Linux based system. A current Ubuntu LTS, i.e. 22.04 or 20.04, is recommended and should be used. Windows 10 or 11 as well as MacOS are conceivable but are not preferred or recommended. Most notations are written in such a way that these systems could also be used in theory.

System packages for Python 3

The pivot point as "programmed documentation" is a fully functioning Python 3 runtime environment. For later setup of a local Python 3 Virtual Environment the following system packages are mandatory and must be installed:

$ sudo apt install --yes $(cat dpkg-tools-reqirements.txt)
$ sudo apt install --yes $(cat dpkg-python3-reqirements.txt)

… or as alternative without an already checked out local repository:

$ sudo apt install --yes \
       $(git archive \
             --remote=ssh://git@github.com:tiacsys/bridle-tutorials.git \
             --format=tar main dpkg-tools-reqirements.txt 2>/dev/null | tar xO)
$ sudo apt install --yes \
       $(git archive \
             --remote=ssh://git@github.com:tiacsys/bridle-tutorials.git \
             --format=tar main dpkg-python3-reqirements.txt 2>/dev/null | tar xO)

System packages for spell checking

If you consider running Sphinx's spell checking extension, the following system packages must be installed:

$ sudo apt install --yes $(cat dpkg-spelling-reqirements.txt)

… or as alternative without an already checked out local repository:

$ sudo apt install --yes \
       $(git archive \
             --remote=ssh://git@github.com:tiacsys/bridle-tutorials.git \
             --format=tar main dpkg-spelling-reqirements.txt 2>/dev/null | tar xO)

Get Started!

Ready to contribute? Here's how to set yourself up for local development.

  1. Fork the repo on GitHub. Clone locally and change into the folder.

  2. Create and activate a project specific Python 3 virtual environment:

    $ python3 -m venv --prompt="$(basename $(pwd))[$(python3 --version)]" \
                  --clear --copies .venv
$ source .venv/bin/activate

$ pip3 install --upgrade pip setuptools
$ pip3 install --upgrade poetry

  3. Install the project dependencies with Poetry:

    $ poetry install --no-root

  4. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  5. When you're done making changes, check that your changes pass our tests:

    $ ### NOT YET ### poetry run pytest
$ ### NOT YET ### make doctest
$ ### NOT YET ### make coverage ; cat docs/build/coverage/python.txt
$ make -C cytron-maker-rp2040 spelling
$ make -C cytron-maker-rp2040 linkcheck

  6. Linting is done through pre-commit. Provided you have the tool installed globally, you can run them all as one-off:

    $ pre-commit run -a

    Or better, install the hooks once and have them run automatically each time you commit:

    $ pre-commit install --hook-type pre-commit --hook-type commit-msg

  7. Optional run tests on documentation and build them offline:

    $ make -C cytron-maker-rp2040 html
$ python3 -m http.server -d cytron-maker-rp2040/build/html 8000
$ xdg-open http://localhost:8000/

  8. Optional run tests on the PDF manual and build them offline:

    $ make -C cytron-maker-rp2040 rinoh
$ xdg-open cytron-maker-rp2040/build/rinoh/bridle-tutorial.pdf

  9. Commit your changes and push your branch to GitHub:

    $ git add .
$ git commit -m "feat(something): your detailed description of your changes"
$ git push origin name-of-your-bugfix-or-feature

    Note: the commit message should follow the conventional commits. NOT YET We run commitlint on CI to validate it, and if you have installed pre-commit hooks at the previous step, the message will be checked at commit time. NOT YET

  10. Submit a pull request through the GitHub website or using the GitHub CLI (if you have it installed):

    $ gh pr create --fill

Pull Request Guidelines

We like to have the pull request open as soon as possible, that's a great place to discuss any piece of work, even unfinished. You can use draft pull request if it's still a work in progress. Here are a few guidelines to follow:

  1. Include tests for feature or bug fixes.
  2. Update the documentation for significant features.
  3. Ensure tests are passing on CI.

Tips

To run a subset of tests:

$ ### NOT YET ### make pytest tests

Making a new release

The deployment should be automated and can be triggered from the Semantic Release workflow in GitHub. The next version will be based on the commit logs. NOT YET This is done by python-semantic-release via a GitHub action. NOT YET