Git Support

Gitflow Branch Handling

We have 2 primary branches:

• main branch containing application code at the latest release
• dev branch containing the code with the latest working features

At each sprint, the dev branch is merged in main and a new release of the application is created: e.g. when there are enough features or when a milestone ends. To add new features to the project, create a new branch from dev and then add the new code in such newly created branch. Once a feature is completed, a pull request must be created from your newly created feature branch to the dev branch. This request will allow other people to see your changes, and request suggestion for you to fix in GitHub through comments. The easiest way to handle branches, merges, rebases is using the GUI for git in your IDE. PyCharm recommended and just ask us for further practical explanations :D.

Branches

Naming convention: type/description. Type will usually be feat (feature) but it could also be fix or docs. The description is a very short and complete description of the task, written in kebab-case dashes-instead-of-spaces: e.g. a branch in which you want to implement the knowledge base creation will be called feat/knowledge-base-creation.

Commits

The general structure of a commit is the following

Commit Message

Commit Body

Co-authored-by: Name Surname

Commit Message is a title about what changed. If you can't sum up your changes into one commit message title, probably you need to split code changes into multiple ones, selecting only the files or lines of files interested.

Commit Body provides the reason of your changes and further technical details of how it was made. Provide a meaningful message of what you accomplished in commits.

Example: if you added a new feature in the project as a basic KPI calculation, your message will be like "added basic KPI calculation in the KPI Calculation Engine" and not something like "modified kpi_calculation_engine.py". Commits with message of the kind fixes, added, some-stuff will NOT be tolerated.

The co-autorship has to be included only in case some code has been shared by multiple developers but committed and pushed only by one of them. If not the case, just ignore it.

Issues

Issues will mainly be focused on a specific user story and assigned to all people working on it. Each issue will have some sub tasks that represent units of work to complete the requirements of the user story, as defined (for example) in the RACI matrices of each team. Make sure to check every sub task as completed as soon as you complete it, in order to have a realistic idea on how fast tasks completing the tasks.

To mark a task as complete you just need to click on it and change its status to closed!

Code Owners

Each repository has a CODEOWNERS file in the .github/ folder. This file lists the "code owners" of files or directory in the repository, in a way that resembles a .gitignore file. Code owners are people that are required to do a code review in a pull request when such pull request modifies files assigned to them. Also entire teams can be code owners.

More details on code owners can be found in the documentation page.

The code owner dynamic is there to

• Avoid self-approval of pull requests, and enforce the reviewing of the code before merging
• Simulate the dynamic of Responsible and Accountable of the RACI matrices

Editing the CODEOWNERS file

People are encouraged to edit the CODEOWNERS file to embed the structure of the organization and the responsibility of each of its member into the structure of the repository.

The file can be edited by the admins, since they are free to commit & push, or by the users themselves by opening a pull request to merge the changes made to the CODEOWNERS file in the dev branch.

Editing the CODEOWNERS file follows the same logic as editing any other file, i.e. the owner of the file, or of the .github folder, will be automatically added as reviewer and must approve the merge (the priority depends on the order, and follows the rules of the CODEOWNERS file). If there's no such owner, the default owner of the repository will be added.

Therefore, modifications are subject to approval, and have to be agreed upon

Pull Requests

Every type/xxx branch must be merged in dev with a pull request.

For every ready pull request there will be a code review. Code will be reviewed, and suggestions on how to improve the implementation may be issued by the reviewers.

Once all the review suggestions are fixed, you will be allowed to merge your branch. Create a pull request even if your code is not ready, in order to let reviewers see it.

To mark your merge request as not ready, its title must start with Draft: . By default the pull request will have as title and description the information of the last commit, please change it: put a meaningful title, a description if needed.

In the description, add the line Closes #id, where id is the issue number that you are implementing: if you type the # character, GitHub will give you suggestions. This way, when your pull request is merged, your issue will be automatically closed. After creating the PR, even if the CI pipeline of actions succeeds you must not merge without having the code owners' approval, hence your code must be approved.

Code owners and Pull Requests

All the code owners of the files modified by the pull requests are automatically added as reviewers. That is, if multiple files - owned by different users - are modified in the pull request, then all the relative code owners are asked for review. The approval of all the reviewers is needed to merge the pull request.

Before opening a Pull Request, GitHub will show who's going to be the reviewer.

Very Important

Do not mess up 😉 if you are not sure, just ask on Telegram or to someone in person.