Adapter/CVS-Conventions

Branches

There are four types of branches, and every branch has to be one these four types.

Branch types:

  • Development-Branch
  • Release-Branch
  • Issue-Branch
  • Personal-Branch

All of these branches are on top level, they are not in folder or contain any folders. The branch structure is flat (depth=1).

Development-Branch

This is the master branch.
The Development-Branch is carrying ongoing development towards a next minor or major release.
The Development-Branch is where all “RC-tags” are applied.

Release-Branch

Release-Branches have the naming key Release_<major>.<minor> (e.g. “Release_2.1”).
Once a certain RC being regarded as ready to be released as either a minor or major release, a Release-Branch will be branched off from this RC (naming-key above).
The Release-Branch is where all “Release-Tags” are apllied. The Release-Branch is carring all the development required to generate “Rolling-Patch-Releases”.
For issues affecting the latest patch-release, the corresponding Issue-Branches will branch off directly from the last commit of the Release-Branch (rolling-patch-release means latest is greatest).

Issue-Branch

Issue-Branches have the naming key gitea-<Issue-Nr> (e.g. “gitea-99”).
If an issue is non-trivial (requires more than 1 commit), it needs to be implemented/solved in a separate, corresponding branch. The branch will be branched off from the affected version.
If the issue is trivial (1 commit), an Issue-Branch is not required.

Personal-Branch

You can do whatever you want in this type of branch.
But, it is officially not existing.
That means it cannot be referenced AT ALL.

Commits

Commits can be issue-related or not.
If they are not issue-related, they are Free-Commits.
If they are issue-related, they can be part of an Issue-Branch or not.

Commit Contexts:

  • Free-Commit
  • Issue-Related-Commit
    • Issue-Related-Commits not part of an Issue-Branch
    • Issue-Related-Commits part of an Issue-Branch
    • Issue-Related-Merge-Commits

Commit Messages

The guidelines here are a loosely based on Conventional Commits.

The commit message contains:

Title

  • Issue-Relationship: It REFERENCES (not copies) an item in the issue tracker or another suitable documentation tool.
  • Type: FIX, TEST, DOC, BUILD…
  • describe what you did

Body

  • BRIEF: Max. 240 chars
  • Desired effect of the change, maybe, but very briefly why.

The CVS is NOT your Issue-Tracker

Please do not store any information into the commit body, that

  • is not also in the issue itself.
  • would be redundant with the issue contents

Yes, in other words, nothing in case there is an issue for it. There is one exception, and that is elaborations about implementation-detail.

Why Not?

  • Avoiding redundance
  • Avoiding out-of-sync contradicting documentation
  • The CVS in NOT an issue tracker.
  • The CVS is also NOT a wiki
  • The contents of commit comments are REFERENCES to an issue tracker or another suitable documentation tool.

Free-Commits

Free-Commits are used whenever anyone who has gained the trust to have write permissions to the repo, wants to make any kind of changes for whatever reasons.
Free-Commits have the following convention that is very welcome, but not mandatory:

Title: <Category>: <describe what you did>

Commit-Category

The Category can be anything, but please do look at the history and try and identify the patterns and try to continue them. Categories that are very common, and must be used if applicable are:

  • FIX
  • TEST
  • BUILD
  • DOC

An more binding list of categories, for inspiration: Categories

Title: gitea-<Issue-Nr>: <Issue-Title> - [<describe what you did>]

Issue related commits that are part of an Issue-Branch have the same conventions as Free-Commits, but the following scheme is also very welcome, and looks neat in the logs and is grep friendly. Title: gitea-<Issue-Nr>: <describe what you did>

Note: the issue-title is not included. It is part of the merge commit.

The merging strategy for Issue-Branches is using merge commits (no squashing, –no-ff).

Title: gitea-<Issue-Nr>: <Issue-Title>