Workflow

Workflow proposal for the maintenance of Python package pyaxis

This document has to be intended as a guide to start a collaborative work, based on our experience as developers. It must be discussed and accepted by all team members. Of course, it's a "living" document that will evolve with our contributions.

When working on a code repository in Github, it's important to establish a clear workflow for the development team. This helps to ensure that everyone is working towards a common goal and to reduce errors or misunderstandings during the development process.

Next, we'll outline some typical workflows including the versioning system and collaborative tools.

Collaborative Tools

GitHub provides several tools to help teams collaborate effectively and efficiently on code development. We shall use the following:

• Issues -> used to track bugs and external feature requests.
• Discussions -> used to discuss code changes, ask questions, and share ideas with team members. Can be linked to code changes or pull requests.
• Pull requests -> before merging changes on master or release branches, pull requests should be created and reviewed by team members.
• Code Reviews -> GitHub provides built-in code review tools that allow team members to review code changes and suggest improvements before they are merged into the codebase.

Versioning strategy

A versioning system is essential for managing code development and tracking changes. In most development projects we use Semantic Versioning:

• MAJOR version: no backwards compatibility API changes.
• MINOR version: new functionality compatible backwards.
• PATCH version: bug fixes compatible backwards.

Unless a deep refactoring, we usually work with MINOR and PATCH.

CHANGELOG

The file CHANGELOG.txt is used to easily get track of version changes.

Branching strategy

We use Trunk Based Development, a branching model in wich developers collaborate uploading code to a master(or main) branch, creating temporary feature|bugfix branches and publishing from release branches.

• The development team works in master.
• Developers doesn't commit to release branches.
• A feature|bugfix branch must have a short lifecycle (max. two weeks) and will be integrated in master as soon as possible.
• Workflows based on pull requests and reviews are described below.

Workflow

Use case 1: implement a new feature

1. A team member share an Idea.
2. The new feature is discussed and agreed by the development team (DT). The task is assigned to a developer(s).
3. Create temporary feature branch.
4. Develop the new functionality + tests.
5. Make a pull request.
6. The DT reviews the code.
7. Validate pull request and merge with master.
8. Create from master a new release branch. Tag major.minor.0.
9. Remove feature branch.
10. Publish package in Pypi.
11. Drink a beer.

Use case 2: bug fix

1. An issue is reported.
2. Team discussion -> agreement -> assign task.
3. Create temporary bugfix branch.
4. Write code + tests.
5. Make a pull request.
6. The DT reviews the code.
7. Validate pull request and merge with master and compatible previous releases.
8. Tag major.minor.patch.
9. Remove bugfix branch.
10. Publish package in Pypi.
11. Take a coffee.