Development#

If you're interested in seeing who has already contributed to this project, please visit our Contributors page. We appreciate all contributions and look forward to see your name on that list.

It is not necessary to be a programmer to contribute. You can help us with the documentation, new features and finding bugs.

Contribution process is summarized below. We assume that you have an account on github, and familiar with Git.

Development process#

Fork and clone#

  • Go to the Magnopy repository (upstream) and click on the "Fork" button. Now you have your own copy of the magnopy repository under your GitHub account (origin).

  • Clone your fork to your local machine:

    • If you are using ssh-key

      git clone git@github.com:your-username/magnopy.git

    • If you are not using ssh-key

      git clone https://github.com/your-username/magnopy.git

  • Change the directory

    cd magnopy

    Now you are in the root folder of you local repository (local).

  • Add the upstream repository to your local repository

    git remote add upstream https://github.com/magnopy/magnopy.git

  • Pull the latest changes from the magnopy repository if necessary

    git pull upstream main

    or

    git fetch upstream
git merge upstream/main

Set up the environment#

We recommend to use virtual environment (with venv, for example). Once the virtual environment is created and activated, you can install the requirements

  • Package dependencies

    pip install -r requirements.txt

  • For the package development

    pip install -r requirements-dev.txt

  • For the documentation

    pip install -r docs/requirements.txt

  • For the tests

    pip install -r tests/requirements.txt

Note

For the linux and OSX systems there is a scenario defined. It installs all requirements. Note: it does not create a virtual environment for you

make requirements

Enable pre-commit#

We use pre-commit to enforce some rules on the code style. To enable it, run the following command

pre-commit install

Now, every time you commit something, pre-commit will check it for you. If some of the checks fail, pre-commit will automatically fix them and abort the commit. You need to add the fixed files to the staging area and commit again.

Hint

If you want to run pre-commit manually, you can use

pre-commit run --all-files

Develop your contribution#

Submit your contribution#

  • Push the changes to your forked repository

    git push origin feature-name

  • Go to your forked repository on GitHub and click on the green "Compare & pull request" button. Describe your contribution and submit the pull request. Please mention the issue number if your contribution is related to any.

Review and merge#

  • Once the pull request is submitted, the code will be reviewed. If there are any comments, please fix them. You can make the changes locally, commit them and push to the same branch of origin repository and they will be added to the pull request automatically.

  • Once the pull request is approved, it will be merged to the main branch of the Magnopy repository.

Development process in details#