Git guidelines

This page goes over the guidelines of committing and pushing code to the repository. It includes things such as commit messages, when to create branches and how to name them, creating pull requests, etc.

💬 Commit messages

Commiting code is an essential part of the development process. It allows us to track changes, revert to previous versions, and understand the history of the project. Therefore, it is important to write clear and concise commit messages that explain what changes have been made and why. We use our own interpretation of the Conventional Commits standard.

We set the following guidelines for writing commit messages:

• Use a keyword to indicate the type of change that has been made.
• Add the scope of the change.
• Give a descriptive title to the commit.
• If the title doesn't encompass the changes, add a body to the commit message.

Examples

chore(docs): Adjusted the git guidelines

feat(login): Added a login button to the homepage

fix(api): Fixed a bug in the API that caused a crash
Rewrote the farmer controller to use the new structure. Adjusted service and repository accordingly

🌿 Branching

Our project uses a tiered branching model to manage the development and release process effectively. Here's an overview of the different branches and their specific roles:

🔨 Development Branch

• Name: development
• Purpose: Serves as the main hub for all feature development and integration.
• Usage:
  • Feature branches: Developers should create new feature branches from development.
  • Merging: Once development on a feature branch is complete, it should be merged back into the development branch.

🧪 Staging Branch

• Name: staging
• Purpose: Used for pre-release testing. This branch holds release candidates.
• Usage:
  • Pull from Development: Changes from the development branch are pulled into staging to simulate a production environment for testing.
  • Merging: No direct feature development or merging occurs in this branch; it only receives updates from development.

🚀 Deployment Branch

• Name: master
• Purpose: Represents the production environment. This is the live branch where end-users access the final product.
• Usage:
  • Pull from Staging: When a release has been thoroughly tested in the staging branch, it is pulled into master for live deployment.
  • Merging: Like staging, the master branch does not receive direct feature merges but only updates from staging.

📋 Workflow Summary

• Feature Development: Start from development and merge back into the same.
• Testing: Use the staging branch for gathering and testing all features collectively from development.
• Release: Move tested features from staging to master for live environment releases.

This branching strategy ensures that our development processes are smooth and that each release is stable and thoroughly tested.

✏️ Naming Branches

When it comes to naming feature branches, the following format should be used: feature-name. For example, if you’re working on a feature that allows users to upload images, the branch should be named upload-images.

🔀 Pull requests

Depending on the branch that you want to pull your work into, there is a different approach to creating a pull request.

Pulling into development 🔨

After finishing a feature on a feature branch, you should create a pull request to merge your changes into the development branch.

When you want to merge your feature branch into the development branch, follow these steps:

1. Create a pull-request from your feature branch to development.
2. Name the pull-request feature-name into development.
3. If you deem this none self-explanatory, add a description of the feature included.
4. Merge the changes into the development branch. Use the Squash and merge option to keep the commit history somewhat clean.

What git does when you squash and merge

When you squash and merge a pull request, Git combines all the commits from the feature branch into a single commit on the target branch. By doing this we lose the reference to the individual commits, but it keeps the commit history clean and easy to read.

Pulling into staging 🧪

Once a set of features has been merged into the development branch, you should create a pull request to merge the development branch into the staging branch. This allows us to test the features in a more production-like environment.

When you want to merge the development branch into the staging branch, follow these steps:

1. Create a pull-request from development to staging.
2. Name the pull-request development into staging xx/xx/xx where xx/xx/xx is the date.
3. Add a description of the changes that have been made. This should be a summary and shouldn’t include a list of every single change.
4. Merge the changes into the staging branch. Use the Create a merge commit option to keep the commit history of staging and development in sync.

What git does when you create a merge commit

When you create a merge commit, Git creates a new commit that combines the changes from the source branch into the target branch. By doing this, we keep the commit history of both branches intact, which can be useful for debugging and tracking changes.

Pulling into master 🚀

Creating pull requests for the master branch should only happen when the code has been thoroughly tested and is ready for deployment. This also includes permission from either the project manager or the team lead.

BEFORE PULLING CHECKLIST

• Email Henk with the changelog and known issues.
• Update the sidenav for each POV with the isNew, isUpdate, and isPrototype flags where necessary.
• Please change the version number in the GitHub vars section.
  • Also, make sure to update the version number in the parent POM.xml file. In your local .env you can change the value as well. This is not required but does introduce a bit of consistency. Inform the team about the changes that have been made so that they can change the version number in their local .env files.

Caution!

⚠️ Keep in mind that this deploys to production automatically! ⚠️

When merging staging into the master branch, follow these steps:

1. Create a pull-request from staging to master.
2. Name the pull-request staging into master Vx.x.x where x.x.x is the version number.
3. Add a description of the changes that have been made. This should be a summary and shouldn’t include a list of every single change.
4. Assign either Rik or Maarten as a reviewer.
5. Wait for the reviewer to approve the pull-request.
6. Merge the changes into the master branch. Use the Create a merge commit option to keep the commit history of master and staging in sync.