Code Repository

Repository Name

From time to time, developers refer to an old project as a reference when working on a new and similar one, hence repositories should be easy to search by its name, clear and self-explanatory.

Convention

• It should be all in lowercase
• It should be in kebab case, using hyphen (-). Correct: nac-pholivery. Wrong: nac_pholivery or NAC-Pholivery
• For project based repository from a recurring client, it should start with the known short code of the client name, such as bsif for Bank Syariah Indonesia Finance, bcad for BCA Digital, and so on. This should be in sync with the client code in CRM.
• The second part should be the known code name of the project. For example online-galleries for Online Galleries, emeterai for E-Meterai application and so on. Again, this should be in sync with the client code in CRM.
• The next part should be the domain specific part of the project. For example backend for Backend part, frontend for web application part, mobile for mobile app developed using hybrid framework such as Flutter or React Native, android and ios each for mobile app developed in native.

Repository Description

Repository name is limited in character (40 characters max in Github), so description (or Project Description in Gitlab) is the best way to explain in brief about the repository while it's still searchable and showing in search results.

Convention

• It should at least explain the repository name. For example, the description for bcaf-emeterai-backend repository should be "BCA Finance E-Meterai Backend" at the minimum, this way at least we know what bcaf stands for.
• It should contains the main technology or framework used. For example, "BCA Finance Virtual Mall Backend Using Spring Boot", this way we can easily search repository based on major framework or technology such as Spring Boot, Laravel, Angular JS, Flutter and so on.
• If necessary put the programming language used to differentiate with other. For example put Kotlin to differentiate with other project using Java, or put Swift to differentiate with other project using Objective C.

README

README as the name implies is the first document that anyone would be asked to read before exploring the source code files. Most source control put README as the front page of a repository. It should tells what a repository is all about in a clear and instructive way.

Convention

• It should contains an overview or general information about the project
• It should contains technology used
• It should contains setup instruction, most importantly development setup for other developer
• Optionally contains screenshots or architectural diagram

Branch Name

Git offers flexible branching strategies which is really useful for collaboration and CI/CD automation. However, not using appropriate naming conventions leads to confusion and complicates the code maintenance.

Convention

Generally, there are two kinds of branches: Regular & Temporary Branches.

Regular Git Branches

These branches will be available permanently in a repository.

• main is the main branch and used for production. It should be stable all the time and no direct commits are allowed. Changes in this branch should be done ONLY by merging from other regular branch such as staging.

• staging contains all the code for QA, user testing or automation testing of all changes implemented. Before any change goes to production environment, it must go through this branch.

• development is the main development branch. This is where all developers contribute to project by commiting changes directly or using Pull Request (PR). The later is more preferable.

Optionally, there may be additional Git branches that need to be kept permanently in a repository. For example, to mark a certain milestone (e.g: sprints) or different environments or architecture (e.g: OS versions). Some conventions that need to be followed are:

• make it as short as possible: ubuntu20 instead of for_server_with_ubuntu_version_20
• use underscore as separator: multi_module not multi module. This is the only place in this standard that uses underscore. Repository names and temporary branches use hyphen
• ask yourself whether it is necessary to keep it permanently in the repository, otherwise use temporary git branch

Temporary Git Branches

As the name indicates, these are branches that can be created and deleted when needed. Temporary Git branches are also used for developers to work on a certain task assigned to him, which later merged to the main branch.

For naming use the following format,

group/description

group is used to group the branch by its purpose, which can be as follows:

• fix for Bug Fix Branches: contains fixes for known bugs or QA findings
• hotfix for Hot Fix Branches: contains urgent fixes, usually small changes and immediate to fix a problem in production, hence the urgency
• feat for Feature Branches: new features that eventually be merged into regular branch
• docs for Documentation Branches: contains documentation changes only, without any change to the code
• chore for Chore Branches: contains changes an external user won't see, such as tooling, build configuration or repository housekeeping
• experiment for Experimental Branches: contains experimental code with new library, architecture, tools etc that need to be shared with others
• wip for WIP (Work In Progress) Branches: contains works that won't be finished soon or need to be completed by other

Use the short form exactly as written above. feat is the group name, not feature, and fix is the group name, not bugfix. Older branches created before this was settled use the longer names; leave them alone and use the short form from now on.

description describes the branch using the following conventions:

• use all lower case: fix/login not Fix/Login
• use noun: feat/ldap-integration instead of feat/integrates-ldap
• use hyphen (-) as separator: wip/payment-gateway not wip/payment gateway
• when it correlates to a certain task in JIRA or other project management tool, put the issue number right after the group: feat/PHOL-19-clear-logo, in this case the issue number are in capital letters which is fine. Leave it out only when there is no task at all
• see the Git Workflow page for when to create the branch, where to create it from, and how it gets merged.