New Branching Model

[CalvinWilkinson]

We are moving to a new branching model!! With this change comes developer experience improvements that are not only for the maintainers but for outside contributors as well.

These changes will help us move faster and improve everything overall!!

Below are some basic questions and answers.

Why the change?

Velaptor has been mostly developed by a single developer. Having lots of CICD and GIT experience in enterprise environments, we wanted to take advantage of our knowledge to make sure that the development process was restrictive so that issues wouldn't slip through the cracks.

Over time, we added slick scripting and CICD automation to make the development process more reliable. Those improvements made it easier to move away from the older and more complicated branching model, without sacrificing reliability.

Velaptor has been in development for about 3 years now and the API has vastly matured! We have also been receiving more outside contributions (🙏🏻). Due to these factors, we changed the branching model to better suit outside contributors. We want the contribution experience to be as easy as possible for you guys!!

Benefits:

1. Faster development cycle.
2. Less time managing issues and pull requests.
3. Less confusion for outside contributors.
4. Easier CICD capabilities, setup, and maintenance.

Is there documentation on this?

Currently, our contribution guide reflects our old, more complicated branching model. The documentation for the updated branching model is currently a WIP. This shouldn't take too long, so please be patient. If you have any questions whatsoever, please reach out to us on Discord and we can help you out!!

What are the contribution basics?

There are 2 main concepts: Production and Preview. If you are contributing to Velaptor for a production version, create your feature branch from the main. If you are contributing to Velaptor for a preview release, create your feature branch from the preview branch.

Note All pull requests will merge into the same branch that the pull request was created from. If you created your branch from the main branch, the PR will merge into the main branch. The same goes for preview branches.

I have contributed before using a fork. What do I change?

With our branching model changes, comes a new name for the production branch of our repositories. The master branch has been renamed to the main branch, which is the recommended name for production branches for GIT. This means you need to update your fork with the new name changes. To do that, you should be able to fetch the new branch which is named _main_and delete the old master branch. Another way would be to recreate your fork entirely. If you have any issues, please reach out, we're happy to help!

Note All KinsonDigital repositories will be converted to the new branching models and the master branch will be renamed to main.

Why was the master branch not named main in the first place?

Honestly, we've been really busy and with our CICD and automation systems depending on the master branch, it's taken a while. We also decided that since we are changing our branching model, this is the best time to do this change!! 😀

What does a feature branch look like?

We use simple rules for the naming convention of the branches.

Warning Please follow the naming convention!! If the branch name is not valid, the CICD system will reject it and the pull request will need to be recreated.

Rule 1: The branch must be in all lowercase letters
Rule 2: The branch must start with 'feature/'
Rule 3: The next piece of text after the 'feature/' section of the branch should be the issue number.
Rule 4: The next piece of text should be a single hyphen.
Rule 5: The next piece of text is a short description with each word being separated by hyphens.

Note You don't have to have the description match the issue title exactly!! Short and sweet is fine.
The issue number in the name of the branch will tie the branch to the issue which will give more info and context.

Examples of valid branches:

• feature/123-my-feature
• feature/124-fix-http-request-url
• feature/14-refactor-class

Examples of invalid branches:

• feature/123-MY-feature
• feature/124fix-http-request-url
• feature/14-refactor class
• feature91-invalid-branch

What is this syncing system?

We've built a custom syncing system!! This means when you create a pull request, the title, assignee, reviewers, labels, project, and milestone will sync to match the associated issue. This not only saves us a ton of work but also makes it much easier to keep outside contributors updated from a pull request perspective.

If the assignee, reviewers, labels, project, and milestone are changed on the issue after the pull request has been created, the pull request will be automatically updated.

Note If the title is changed on the issue, the PR title will not be updated.

Do I still need to use pr templates?

Nope! You don't need to worry about pull request templates anymore! The custom syncing system we built automatically syncs the information from the issue to the pull request. Please see the What is this syncing system? for more information.

Note Currently, Velaptor and CASL are the only projects using the new branching model. The rest of our projects are going through the process.