4.2. Collaborate

You can PyPackIT can use your help in many different ways; a few examples of how PyPackIT can appreciate from your experience, support, knowledge and expertise are:

So, thank you for your support and involvement; we appreciate all your work! 🙏❤️

Our community aspires to treat everyone equally and to value all contributions. We have a Code of Conduct to foster an open and welcoming environment.

Why should I read the contributing guidelines?

As most of us have surely experienced, maintaining a free and open-source project is not a trivial task, and the need for coordination between different contributors who are not all in contact with each other adds another layer of complexity to the job. To value every volunteer’s time and efforts, we have devised detailed instructions for how to join the conversation and become a part of the community. These guidelines aim to standardize the development and maintenance process, so that a large portion of the pipeline can be automated. By following these instructions, you ensure that you and every other member is making the most out of their time and efforts.

If you are new to contributing to open-source projects, we also recommend reading the Open Source Guides, particularly: How to Contribute to Open Source.

4.2.4. Become a Collaborator

  • writing code; fixing bugs, improving performance and quality, and adding new features

  • adding examples and tutorials to the documentation

  • proofreading, editing and writing documentation

It starts by describing the general development cycle of the project, followed by detailed instructions for different types of contributions. If you are interested in becoming an active member or a maintainer of the project, we strongly advise you to read all sections chronologically. Otherwise, you can read the general notes and then head down to the section addressing the type of contribution you want to make (see left sidebar), for example reporting a problem or contributing code.

4.2.6. Development Cycle

Our “headquarters” is our GitHub repository (always accessible via the icon on the top-right navigation bar), where we host, develop, manage and maintain our project, and communicate with each other.

Get started with GitHub

If you are unfamiliar with GitHub, please take a look at the GitHub Documentation and read the GitHub Quickstart. Don’t forget to create a free account.

We have adopted the GitHub flow to contribute to the project, and use GitHub Discussions as the starting point for most of our communications. With a standardized workflow, almost all activities in PyPackIT follow the same steps.

Also have a look at GitHub documentation on planning and tracking tools .

Also have a look at GitHub documentations on communicating and socializing on GitHub.

Fork repo ABC Clone it locally (git clone git@github.com:jmeridth/jekyll.git) Add upstream repo (git remote add upstream git@github.com:mojombo/jekyll.git) Create a feature/topic branch (git checkout -b awesome_feature) Code fix/feature don’t forget to add tests/specs and make sure they pass Commit code on feature/topic branch (git add . && git commit -m “awesome”) Checkout master (git checkout master) Pull latest from upstream (git pull upstream master) Checkout feature/topic branch (git checkout awesome_feature) Rebase your changes onto the latest changes in master (git rebase master) Push your fix/feature branch to your fork (git push origin awesome_feature)

4.2.6.1. Create a Discussion

Regardless of whether we are a member of the core development team or a first-time contributor, when we think something should be fixed, changed, added, or removed, or simply have a question, idea, announcement, or anything else we want to share with the community, we start by creating a new discussion topic in the relevant category; for example, a discussion titled ‘Graphical user interface (GUI)’ in the New Features category, to discuss the idea of adding a GUI to the application.

4.2.6.2. Create an Issue

Before creating an issue, you have to make sure the issue

4.2.6.3. Bug

First, there are two thing you have to make sure of:

  1. What you are experiencing is actually a bug in the application, and not the intended behavior, or the result of not following the instructions.

  2. The bug has not yet been fixed or reported by anyone else.

Additionally,

  1. Create a new virtual environment on your machine. This provides an isolated environment to ensure that the bug is indeed caused by our application.

  2. [Download and install] the latest development version directly from our repository into the new environment.

4.2.6.3.1. Verify the bug

4.2.6.3.2. Make sure the bug still exists

After verifying the bug, you have to make sure that it has not yet been fixed or reported. To do so, we highly recommend the following steps:

Search in Discussions and in issues and pull requests with several different keywords to make sure the issue has not already been reported.

creating an issue. After the community discusses the topic, if the consensus is that some action is required, an issue is created from the corresponding discussion topic. A maintainer is automatically assigned to each opened issue, which can then also assign other volunteering contributors.

4.2.6.4. Create a Branch

Clone the repository if you have write access to the main repo, fork the repository if you are a collaborator. Make a new branch with git checkout -b <your branch name>

When you are assigned to an issue create a development branch

  1. If you are not a core developer of the project (and thus don’t have write access to this repository), fork this repository first.

  2. On your fork (or on this repository when you are a core developer), create a new branch from the main branch

Clone the repository.

If you have write access, you can also directly create a branch from the issue

Naming rules for branches:

Other than the ‘main’ branch, we have the following types of branch names:

  • release/v[0-9]+: Release branches for each past major version, e.g. release/v1 is created when version 2.0.0 is released.

  • dev/(app|docs|test|ops)/[0-9]+: Development branches for applying changes, e.g. dev/app/11.

The assignees then create a new branch from the repository’s main branch, to work on the issue. If you are a core developer (and thus have write access to the repository), you can simply create a new branch in the project’s repository. Otherwise, you must first fork the repository, and then create a new branch from the fork’s main branch.

For members with write access

If you are a core developer or maintainer of the project and thus have write access to the repository, instead of forking the repository and creating a branch on your fork, you can instead directly create a new branch on the repository.

The branch must be named: dev-{issue number} (for example: dev-11)

About Branches

Learn more about branches on GitHub Documentation

4.2.6.5. Commit Changes

After cloning the repository (or your fork of the repository) on your local machine, .

We use conventional commits.

Use pre-commit hooks.

Run tests. When the code is ready to go, make sure you run the test suite using pytest.

If you’re providing a new feature, you must add test cases and documentation.

Ensure that the test environment dependencies (conda-envs) line up with the build and deploy dependencies (conda-recipe/meta.yaml)

Ensure the code style and formatting by running black and isort.

Push the branch to the repo (either the main or your fork) with git push -u origin <your branch name>

  • Note that origin is the default name assigned to the remote, yours may be different

4.2.6.6. Create a Pull Request

When you are ready for others to examine and comment on your new feature, navigate to your fork of PyPackIT on GitHub and open a pull request (PR).

There are many ways to create pull requests .

Pull requests from forks can be created on the GitHub web UI but we use URls with query parameters to directly load the correct template:

We advise you to regularly sync your fork with the main repository.

For core developers: sync your branch

Note that after you launch a PR from one of your fork’s branches, all subsequent commits to that branch will be added to the open pull request automatically. Each commit added to the PR will be validated for mergability, compilation and test suite compliance; the results of these tests will be visible on the PR page.

Don’t forget to link the pull request to the corresponding issue. If you are a maintainer, you can do this either from the pull request sidebar or the corresponding issue sidebar. Otherwise, use a keyword in your pull request (e.g. Resolves #11).

When you’re ready to be considered for merging, check the “Ready to go” box on the PR page to let the PyPackIT devs know that the changes are complete. The code will not be merged until this box is checked, the continuous integration returns checkmarks, and multiple core developers give “Approved” reviews.

4.2.6.7. Review and Merge Pull Request

4.2.6.8. Publish New Release

  • git tag -a X.Y.Z [latest pushed commit] && git push --follow-tags