UNUSUALIFY SPECIFICATIONS

Git Branching Conventions

Introduction

This conventions target you to follow descriptions strictly, besides it will diminish confusions and take away senseless messes from a git repository flow. Branching conventions make your repo robust and more followable.

Basic Branches

While construction git repo, you should have main(default) and dev branches. This branches keep retained on repo, and changes or commit never be made in this repos. The object of this branches is to merge commits, publish releases.

• feature: All features / new functions / major refactorings are done in feature branches, which branch off and are merged back into the dev branch (usually after some kind of peer review).
• release: When enough features have accumulated or the next release time frame comes near, a new release branch is branched off develop. It is solely dedicated to testing/bug fixing and any cleanup necessary (e.g. changing some path names, different default values for instrumentation etc.)
• main: the release branch is merged into main (and also back to develop).main branch is merged with only release branch before publishing a release.
• hotfix: If a major problem is found after release, the fix is developed in a hotfix branch, that is branched off the master. Those are the only branches that will ever branch off of master.

Basic Rules

1. Lowercase and Hyphen-separated: Stick to lowercase for branch names and use hyphens to separate words. For instance, feature/new-login or bugfix/header-styling.
2. Alphanumeric Characters: Use only alphanumeric characters (a-z, 0–9) and hyphens. Avoid punctuation, spaces, underscores, or any non-alphanumeric character.
3. No Continuous Hyphens: Do not use continuous hyphens. feature--new-login can be confusing and hard to read.
4. No Trailing Hyphens: Do not end your branch name with a hyphen. For example, feature-new-login- is not a good practice.
5. Descriptive: The name should be descriptive and concise, ideally reflecting the work done on the branch.

Branch Prefixes

Using prefixes in branch names helps to quickly identify the purpose of the branches. Here are some common types of branches with their corresponding prefixes:

• Feature Branches: These branches are used for developing new features. Use the prefix feature/. For instance, feature/login-system.
• Bugfix Branches: These branches are used to fix bugs in the code. Use the prefix bugfix/. For example, bugfix/header-styling.
• Hotfix Branches: These branches are made directly from the production branch to fix critical bugs in the production environment. Use the prefix hotfix/. For instance, hotfix/critical-security-issue.
• Release Branches: These branches are used to prepare for a new production release. They allow for last-minute dotting of i’s and crossing t’s. Use the prefix release/. For example, release/v1.0.1.
• Documentation Branches: These branches are used to write, update, or fix documentation. Use the prefix docs/. For instance, docs/api-endpoints.

Unusualify Branching Commands

You need to install Shell Scripts at first for using git aliases in naming branches with conventions.

  cd ~ 
  git clone https://github.com/OoBook/shell-utils.git
  git config --global include.path "shell-utils/.gitaliases"

Branch types

You run 'git new-{type}-branch {case-name} origin/dev' for branching off dev branch, while creating new any type branch. Default type: feature.

For example, you need to create a bugfix branch for 'header-issue' case. This will create a branch named "bugfix/header-issue".

  git new-bugfix-branch header-issue origin/dev

For example, you need to create a docs branch for 'api-post-endpoints' case. This will create a branch named "docs/api-post-endpoints".

  git new-docs-branch api-post-endoints origin/dev

Sproud Flow

We have defined an alias 'sproud' that makes your flow instead. It's branching off dev branch, and you can continue your flow. Default branch type: feature. Only run commands as following:

• With only require parameter case name

    git sproud {case-branch}
  

• With branch type

    git sproud {case-branch} hotfix
  

If your branch working is not done yet

As same sproud alias, but this command makes a stash and checkout your branch.

• With only require parameter case name

    git sproud-stash {case-branch}
  

When your works is done in new branch, for returning previous uncompleted branch, you need to run only as following:

  git go-back

Git Commit Conventions

Introduction

A commit message indicates how a developer is great collaborator

Vscode Extension

This extension presents some advanced eases for commit messaging convention and following specifications to be described below.

Name: Conventional Commits
Id: vivaxy.vscode-conventional-commits
Description: 💬Conventional Commits for VSCode.
Version: 1.25.0
Publisher: vivaxy
VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits

Commit Structure

<!-- Subject Line: -->
<type>[optional scope]:<description>

<!-- Body Line  -->
[optional body]
Because:
- [relevant context]
- [why you decided to change things]
- [reason you're doing it now] 
 
<!-- Footer Line -->
[optional footer]

Subject Line

Type

• feat: use for code features -> MINOR RELEASE
• fix: use for bug fixes -> PATCH RELEASE
• docs: use for docs like .md, .yml .etc
• style: use for commits, that do not affect the meaning (white space, formatting, missing semi-colons, etc)
• refactor: use for code refactoring but not change any behaviour
• perf: use for refactoring commits, that improve performance
• test: use for adding test files, correcting files
• build: use for built resources
• ci: use for continuous intregrations
• chore: use for small updates eg. .gitmessage, composer.json
• revert: use for return from a commit

Optional Scope:

• additional info
• with nouns

Description:

• short
• imperative

• do not use a period mark in end of subject
• up to 50 characters

Body Area

Optional Body:

• explain in way you want
• detailed
• why, how, what

Footer Area

Optional Footer:

• followed by either a :_space or _space# separator,
• followed by a string value
• use "-" in place of whitespace characters (kebabcase)

Examples

Commit message with description and breaking change footer

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Commit message with ! to draw attention to breaking change

feat!: send an email to the customer when a product is shipped

Commit message with scope and ! to draw attention to breaking change

feat(api)!: send an email to the customer when a product is shipped

Commit message with both ! and BREAKING CHANGE footer

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

Commit message with no body

docs: correct spelling of CHANGELOG

Commit message with scope

feat(lang): add Polish language

Commit message with multi-paragraph body and multiple footers

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

Composer Versioning

Version Range (>,=,<,!)

• =1.0

• =1.0 <2.0

• =1.0 <1.1 || >=1.2

Hyphenated Version Range (-)

• 1.0.0 - 2.1.0 :: >=1.0.0 <=2.1.0

Wildcard Version Range (.*)

• 1.* :: >=1.0 <2.0
• 1.0.* :: >=1.0 <1.1

Tilde Version Range (~)

• ~1.2 :: >=1.2 < 2.0.0
• ~1.2.3 :: >=1.2.3 <1.3.0

Caret Version Range (^)

• ^1.2.3 :: >=1.2.3 <2.0.0
• ^0.3 :: >=0.3.0 <0.4.0
• ^0.0.3 :: >=0.0.3 <0.0.4