Branches naming scheme

[ddnomad]

I propose to introduce a fixed git branches naming scheme. It would make merging and overall developer interaction a little bit more intuitive. Moreover it would allow us to maintain more gradual access control across the whole repository (each developer has access only to <developer>-* branches of his own). Branches would be named like the following:

• <developer>-exp - experimental features and proves of concept. Should not be merged into master or other upstream branches. Mostly serves as a stash for concept sketches and "maybe_implement" type of code.
• <developer>-nightly - WIP branch where an actual development would take place. Should not be merged into master or other upstream branches.
• <developer>-testing - testing branch where release candidate code is polished and prepared for merge with master or upstream branch.
• <developer>-rc - release candidate branch. Could be reviewed by other developers to give feedback or help with a development (fork). Should not be merged into master or other upstream branches.
• <developer>-stable - stable branch. Features that can be merged into master or upstream. The code is tested and is ready for merging into upstream.

In addition at least two "master" branches should exist:

• testing - branch where merged across all <developer>-stable branches features are tested to make sure they work all together.
• master - main branch where only tested, production grade code reside.

Each developer will go through at least <developer>-nightly -> <developer>-stable branches and then submit a pull request to testing. @Neketek then merge all stable branches into testing (or reject if needed) and all developer team makes sure testing branch behave as expected. If everything is working @Neketek then merge testing into master.

As a rare exception developers might create other branches though they must start with <developer>- prefix and developers themselves are responsible for deleting these branches afterwards. Generally, such behaviour is discouraged.

Thoughts?

[Neketek]

@ddnomad It's complex question, I'm thinking about branch merging policy. We need to have decentralized structure because centralized policy slows down the development process and destroys flexibility. Version which you propose is decentralized, but features aggregation in single developer branch can cause problems of fixing branch related bugs.

[Neketek]

@ddnomad Only problem which I have right now is hot fixes. I suppose hot fixes should be added as pull request to development branch or be implemented in separated branch like hf-.

[ddnomad]

@Neketek I was thinking that anyway features tend to be merged into master. So workflow is more or less linear. This approach may cripple though if certain developer would suddenly start working on 3 or more features simultaneously (which is an uncommon scenario in my opinion).

If developer works on 2 features in the same time they can be localized to <developer>-exp and <developer>-nightly respectively.

The issue is that GitHub do not support setting access policy for glob branches (like developer bob can write to any branch matching regex bob-*).

Anyway other suggestions are welcomed as always.

[ddnomad]

OK, hotfixes. We could throw three more branches for each developer named <developer>-hf1, <developer>-hf2 and <developer>-hf3.

Then the issue is solved I presume.

[Neketek]

@ddnomad I will write explanation soon.

[Neketek]

Description:

• master is a branch which reflects current production state.
• release-<version> is a branch which freezes state of development branch to keep track of product releases.
• development is a branch which contains latest features of the product. When we'll decide that current development branch state is stable and new features contained in it are substantial enough, we'll create new release.
• hf-<developer> is a branch or pull request which contains hot fixes which should be applied directly to master branch. To keep branches consistency hot fixes should be also merged into latest release-<version> if it's present and into development branch.
• <developer> - is a personal branch of developer. It serves for merging into it <feature> branches which belong to same developer. It can be merged directly into development or into <epic> branch.
• <feature> is an optional branch which is designed to hold small features which single person can fully implement. Example: login-form, get-user-profile.
• <epic> is a branch which serves for developers collaboration for implementation of the updates which consist of too many features than one developer can potentially implement in an adequate time frame.

[Neketek]

@ddnomad Sure, we can add some prefixes for better understanding of branches purpose, It could be something like f-<feature> - front-end feature, do-<feature> - DevOps feature and so on.

[ddnomad]

@Neketek it seems like you have a typo in the name of dev collaboration branch. Or do you want to name it as a backquote "`"? :)

[ddnomad]

Well, overall it looks nice. I would add prefixes for features (to be discussed) and additional branch for each dev where experimental stuff can be stored and showcased.

[Neketek]

@ddnomad Considering pattern of the development almost everything in the developers branches will be experimental :). For real experiments we can( should) create epics with a description of that experiments. Epics have custom names and probably should have primary prefix ep-. Experiments can be prefixed with ex-. So, if we have experimental epics or simple branches which are kinda experimental we are adding ex- prefix and in result we'll have something like ex-f-s-dynamic-list-loading or ep-ex-f-s-dynamic-list-loading if it's an epic.

[ddnomad]

@Neketek what is s in these names? And what's about dev collaboration branch?

[ddnomad]

@Neketek Any updates? (see my previous question)

[Neketek]

@ddnomad No updates yet, but I'm going to push one soon: prefixes list and some naming changes.

[ddnomad]

Nice

[Neketek]

List of the branch prefixes. Positions in the list represent ordering of the prefixes in the branch name:

• <developer> - personal branch. This prefix should be first in prefixes chain.
• hf - hotfix.
• ex - experimental
• e - epic
• d - devops
• b - back-end
• f - front-end

Example of usage:

1. neketek-ex-e-b-f-web-sessions.
2. ex-e-b-f-web-sessions.

Translation:

1. neketek's experimental epic branch with back-end and front-end implementation of web sessions.
2. experimental epic branch with back-end and front-end implementation of web sessions.

If branch has no <developer> prefix everyone can push to it, otherwise only owner can push to it.
If developer is working not on his main branch(<developer> with no suffixes or prefixes) , he should not merge it directly to development. All developer personal branches should be merged into developer's main branch before merging into development. Branches with no developer prefixes can be merged directly to development because they should be created for implementation collaboration. Most of the time you'll be using your <developer>-ex (personal experimental branch) and <developer> (main branch). Branch manager will pull updates only from you main branches or collaboration branches.

[Neketek]

@ddnomad So, you'll reduce your branches to ddnomad and ddnomad-ex, but you can have unlimited number of the feature branches. I'm asking only to keep personal staging branches locally and to not flood remote with minor features which can be grouped with other.

[ddnomad]

@Neketek ok so far so good. I'll cleanup my branches.

[ddnomad]

@Neketek if I'll have time to spare I can setup git hooks for our project that would ban creation of a branches that do not follow the convention described above. Do we need such a feature?

[Neketek]

@ddnomad Yes, it will be useful, but generally this hook should track only order of static prefixes.

[ddnomad]

Ok, I'll look into it at some point in the future.

[Neketek]

Tomorrow I'll create document which contains all useful information from this issue.