AGS Development > Engine Development

AGS project Branch & Commit Conventions - Proposal Draft

(1/2) > >>

Crimson Wizard:


The branching model for AGS is defined considering the specifics of its development.
The development roughly breaks into following tasks:
1. Developing the Editor
2. Developing the Engine (interpreter) core functionality
3. Developing the Engine ports

The game features provided for creating and editing by the Editor should correspond to the feature support by the Engine. However, particular changes may be strictly related to only one of those programs.
The engine ports sometimes require their own improvements. Compatibility fixes providing support for running older games are usually made in sake of ports, but the changes occur in the Engine's core.


Generally we base the branching model on a following reference:
It seems easy to follow and helps to keep most stable code in the primarily accessed branch, therefore the users who prefer making builds themselves will get the last fixed stable version without searching for proper branch.

On top of this model we add one exception for hotfixes and minor compatibility fixes: we allow them to be applied to master branch directly, and also we allow not to increase the release version after every single immediate bugfix and compatibility fix.
This makes it generally simplier to add ones; and it is still possible for bug reporters to mention the precise program state they used by refering to commit they were at when making the build (by commit hash).
This exception may be removed later should the development process become more complex or should such exception cause troubles.

Branch summary

In summary, the branching rules are following:
master - is a stable branch, which receives merges from "release" and "hotfix" branches when the code is good enough. There are tags, that mark version releases. Changes should not be made directly to "master", with previously mentioned exception of immediate bug fixes and very simple compatibility fixes.
Only "hotfix" and "release" branches could be merged in. This branch is meant for common end-users, who want be sure they are always using "official" stable version.

hotfix - these branches are used when the serious bugs are found in recently made release, that is when the new released code is already in "master". After making commits and testing them, the contents of a branch are merged to "master".

release - auxiliary branches for the final preparations before new version release. It is forked from "develop" branch when it is clear no more features are to be added to the nearest upcoming version. Only bugfixes are allowed. When it is done, it is merged to "master".

develop - main development branch. All new things are done here. When approaching new release, the "release" branch is spawned from "develop". From that moment all fixes to the closest release are done in related branch, and "develop" is used to start working on the next release.

feature - feature branches are temporary auxiliary branches. They are forked from any other branch (presumably from "master" or "develop") by a team or individual developers, to work separately on certain feature. It is strongly recommended to create "feature" branches in personal repositories, rather than in central one, unless it requires attention of multiple developers over a long period of time. The feature may target next upcoming release, or some distant release in future. When finished, it is merged to "develop".

Branch naming

The "master" and "develop" branches always keep their respective names. Other branches are named with regard to the title of version or feature they are dedicated for.
Hotfix branch should be named "hotfix-X.X.X.Z", where X.X.X is the last release version and Z is a new planned build number.
Release branch should be named "release-X.X.X", where X.X.X is the planned version number (without last build number, because it may eventually change).
Feature branch's name should carry the indication of the branch's purpose. It may start with "feature-" prefix for better visibility. It is recommended to give unique and expressive names. For example, "my_new_feature" or "my_work" are bad names, because they do not indicate the feature meaning. "new-script-commands" is not a very good name either, because there may be more than one branch dealing with new script commands.

Branch rules

All branches except "master" and "develop" are deleted some time after they were merged - to solidify their "finished" state (remember this won't delete commits, only branch's header).

The main "develop" branch is meant for working towards next major release. Sometimes it may be planned to make an intermediate minor release, or such need arises unexpectedly. This might be difficult to separate the development of minor and major version in time on one branch, so that major changes come only after minor ones and the minor release would not include them.
In such case it is recommended to create a separate branch named "develop-X.X.X" to work on minor update (where X.X.X is a planned version).
It is forbidden to have more than one major and one minor develop branches at a time. "Feature" branches should be used to work on and store code until the time when it may be merged into "develop".

After hotfix or release is merged into "master", it is recommended to merge them into nearest "develop" one (minor, then major) as soon as possible.
Similarily, when minor development branch is finished to be worked on (and new release branch spawns out of it), it should be merged into main "develop".
It is also recommended to merge "release" and minor development branches into main "develop" from time to time to keep things synced (especially if serious bugs were fixed in the former).

Feature branches carry little obligations. They may be postponed for undefined time, deleted, if appear to be a failure. They may be created solely to experiment on something.

Pull requests.

It is suggested to do most work on new features in personal repositories. Even if the developer has direct access to central repository, it is recommended to create personal branches when working on larger changes that require time to complete, review and test. This prevents from messing up commits from different developers, and also helps to distinguish commits related to certain feature or set of features.

Prior to other things, we recommend to setup a connection between your personal repository and central AGS repository. This page gives general tips on how to do this, and how to synchronize main branches between different repositories:

Pull requests from personal repositories are used to merge developer's changes into central repository.
The most important rule for planned pull request is to work in a separate branch, even if the change is small, one branch per pull request, and one pull request for a feature or closely related set of small features.
This will allow you to keep your new feature code safe, not mess up irrelevant commits, and still be able to sync the main branches ("master", "release", "develop") in your personal repository with ones in central repository.
Remember that, if necessary, you may keep the feature branch unmerged for a long time, and merge only when it is most convenient to do so.
This is also important to remember that in most times there's no need to regularly update your feature branch with changes from "master" (or other main branches). Instead, if the main branch has changed too much, you may rebase your feature branch on top of updated main one. This helps to keep the feature branch and pull request cleaner, which also improves readability of changes history.

Pull requests should never contain irrelevant changes. Consider making two (or more) pull requests with different feature branches if all of those changes are required. If some changes are not needed at all, remove them prior to making pull request. Remember that Git allows to fix and copy branches and individual commits.
If you are making several minor changes that have similar meaning or related to each other consider making one pull request (these changes may be divided into several commits if wanted).

... to be continued with commit conventions.

Comments, suggestions, questions?

I wholeheartedly agree with this; good show CW! (nod)

I don't have much to comment on I guess. Maybe something about forks; I guess there are two layers of developers working on AGS. Those working on the main project with milestones opted by the community and people working on their own fork having their own milestones. I guess some of these forks might contain useful features we want to pull into the mean project. Is that something that should be done by pull requests on the develop branch or should they first put this in a feature branch?

Anyhow, by the looks of these conventions the start-up of open source AGS is maturing, yay! :-D

I feel like this is aimed at me. I've made such a mess of commits, pull requests and branching. I put this mostly down to Git being fairly unforgiving when you make a mistake, but I think I have to accept some responsibility too. I'm sorry CW! I'm getting better at Git, I swear!

Crimson Wizard:

--- Quote from: Gurok on 14 Feb 2014, 00:57 ---I feel like this is aimed at me.

--- End quote ---
Not really. From what I know almost everyone contributing to AGS since it became opensource was new to Git (me too).
We needed this kind of convention for a long time, but I could not be arsed to write one.
Btw, nothing bad happened anyway.

--- Quote from: Gurok on 14 Feb 2014, 00:57 ---I put this mostly down to Git being fairly unforgiving when you make a mistake,

--- End quote ---
Actually it lets you to fix almost everything, although in severe cases that would require collaboration with other people to sync everyone's work.

Sounds good to me as it is.


[0] Message Index

[#] Next page

Go to full version