LinearTapeFileSystem
Branch and Naming Conventions
The following text is an structure proposed to better manage and maintain the code of this project. This was already discussed by the GDL team in several meetings reaching into an agreement on the mentioned rules and conventions.
Branch Naming Conventions
The structure and design conventions are based mainly on the “Conventional Branch” concept and the team’s current work process.
Purpose
- Purpose-driven Branch Names: Each branch name clearly indicates its purpose, making it easy for all developers to understand what the branch is for.
- Integration with CI/CD: By using consistent branch names, it can help automated systems (like Continuous Integration/Continuous Deployment pipelines) to trigger specific actions based on the branch type.
- Better type and version control: Branches are related to a specific type of change in the code and the version that is being worked on, allowing for a much better backtracking.
Basic Rules
- Naming structure:
<type>/<description> - Naming prefixes (Types):
- feature/: For new features (e.g., feature/add-login-page).
- fix/: For general fixes or code correcting.
- update/: For code upgrade or non-breaking code refactoring.
- chore/: For non-code tasks like dependency, docs updates (e.g., chore/update-dependencies).
- release/: For branches preparing a release (e.g., release/v1.2.0).
- Use Lowercase Alphanumeric and Hyphens: Always use lowercase letters (a-z), numbers (0-9), and hyphens to separate words. Avoid special characters, underscores, or spaces.
- No Consecutive or Trailing Hyphens: Ensure that hyphens are used singly, with no consecutive hyphens (feature/new--login) or at the end (feature/new-login-).
- Keep It Clear and Concise: The branch name should be descriptive yet concise, clearly indicating the purpose of the work.
- Include Ticket Numbers: If applicable, include the ticket number from your project management tool to make tracking easier. For example, for a ticket issue-123, the branch name could be feature/issue-123-new-login.
General Project Structure
main
├── release/v1.x.x
│ ├── feature/lorem-ipsum
│ └── fix/ipsum-dolor
├── release/v2.x.x
│ └── chore/dolor-sit
└── release/v3.x.x
├── update/sit-amet
├── feature/amet-consectetur
└── chore/consectetur-adipiscing
- main: This branch should only contain working versions completely tested and only receive pull requests from finalized release branches. All new release/ branches must come from this one.
- release: The creation of these branches should be done from the last version of main when created. Only this branches can make pull requests to main.
- Other branches: All working branches should come from a release branch. These are the only ones that should receive direct commits from changes made by development staff. These branches should only do PR to the active release branch.
Commits Naming Conventions
The structure and design conventions are based mainly on the “Conventional Branch” concept and the team’s current work process.
Purpose
- Automatically generating CHANGELOGs: When the commits are concise, and precise changelogs can be automated or semi-automated from the commit history.
- Communicating the nature of changes to everyone: Being able to understand the type of changing by just looking at a name and understanding the basics of a commit just by the title is useful in analysis and backtrack situations.
- Building code habits and good practices: Maintaining structured commits also leads to more precise coding practices and coherent code changes.
Basic Rules
- Naming structure:
<type>: <description>
[optional body]
- Naming prefixes (Types):
- fix: A commit of the type fix patches a bug in your codebase.
- feat: A commit of the type feat introduces a new feature to the codebase
!: A commit that appends a ! after the type introduces a breaking change. A breaking change can be part of commits of any type. - update: A commit of type update changes existing code or refactors functions without changing functionality of adding features in your codebase.
- build: A commit of type build changes build process in your codebase.
- docs: A commit of type docs is for creation or updating documentation in your codebase.
- chore: A commit of type chore is for every other minor task in your codebase.
- Commits must be prefixed with a type, which consists of a noun, feat, fix, etc., followed by the optional !, and required terminal colon and space.
- A description must immediately follow the colon and space after the type prefix. The description is a short summary of the code changes, e.g., fix: array parsing issue when multiple spaces were contained in string.
- A longer commit body may be provided after the short description, providing additional contextual information about the code changes. The body must begin one blank line after the description.
- A commit body is free-form and may consist of any number of newline separated paragraphs.
Bibliography
[1] “Conventional Branch,” Conventional Branch, 2025. https://conventional-branch.github.io/ (accessed 2025). [2] “Conventional Commits,” Conventional Commits. https://www.conventionalcommits.org/en/v1.0.0/ (accessed 2025).
This space can be used to talk about any questions you may have, or add anyone who should be involved in the change.
This was already discussed by the GDL team in several meetings reaching into an agreement on the mentioned rules and conventions.
What does this mean? Is GDL's decision the decision of this project? If you want change the current process, you need to start fully opened discussion, I believe. I cannot understand the background of this change at all from the description because it just tells the new rules.
Honestly, I cannot understand your intention from this description. Because, now we are requesting everyone who wants to change the code to use their own fork and create a PR on their repository. So new naming convention for feature, fix is NOT required at all.
I'm feeling what you want to do is changing the management flow of this project. Please describe below as a starting point. Discussion must start from here.
- What is the problem of current development process
- What is the solutions you think
- Summary and concept of new development process (Big picture)
- How and when we move to new development process
Hello @piste-jp, thanks for laying down the starting points of discussion.
1.- What is the problem of current development process?
It is not necessarily a problem, but rather an opportunity to improve in two key areas. First commit organization, to have a better view of the contents of a PR with just a look, encouraging developers to write clear, descriptive commit messages and keep their commits well-organized would make code reviews more efficient and help maintain a cleaner project history. Second, the branching strategy; it’s often unclear where branches should originate, where pull requests should be targeted, or how forks should be handled, this lack of structure makes the project history harder to follow and can complicate collaboration and troubleshooting.
2.- What are the solutions?
The proposal we came up as a team in GDL is to implement the use of naming conventions for both commits and branches to promote and encourage more organized code changes, additionally we suggest the change of the structure used in the Github project in a way that all branches serve a clear purpose and it’s easier for community contributors to work on the project.
3.- Summary and concept of new development process (Big picture)
The proposed development process introduces a more structured branching strategy, focused on improving organization, and traceability. The main changes are as follows:
-
main: This branch can only contain stable, production-ready versions. Only completed and tested versions from release/ branches may open pull requests (PR’s) into this one. It should be protected requiring at least 2 code reviewers before any merge is done. (This is tied to deciding how we will manage the v2.4 stable version and the current master branch to make sure we can merge stable changes, or if they need to be separated to avoid conflicts between the community and the use of the software at IBM).
-
release/x.x branches: These type of branches should be created for each new release, branching off the last stable commit on main. All branches created by developers to contribute to this project should branch off from the current active release/x.x branch. It’s purpose will also be used as an integration staging environment for testing before merging into main.
-
Other branches: Other types of branches should come from the working release/x.x branch and can only do PR to the same one where they came from, these are the only ones that should be created by contributors directly and follow the naming conventions on the file described in CONTRIBUTING.md.
Contributors must create their own fork to work on and follow the rules described here and the previous rules already in the contributing file.
4.- How and when do we move to a new development process
The general process would be done in 2 phases.The focus of the first one is to begin applying naming conventions for commits and to establish standardized branch naming for new versions, features, and fixes, following the conventions mentioned above. This can be done immediately since it doesn't affect past work in the project, and it’s best to start using good practices as soon as possible.The second phase consists of evaluating our current use of the “stable” and “master” branches, as both of them contain code that is used for production purposes and are not up to date with each other. We are currently analyzing the differences between these branches and considering if the work done in “stable” could be useful for the community in master, and vice versa. Based on this, we could decide whether to merge the changes and maintain a single “main” branch or continue managing them separately.
With that in mind, do you know why this project does not use the “master” branch for stable versions? We suppose it is primarily because it was wanted to work on LTFS 2.5 support by using a different branch from a stable (used in releases) branch, or is there another reason for this approach?
We intend for the project to grow in a more organized and stable way by implementing these changes and following best practices.
1.- What is the problem of current development process?
It is not necessarily a problem, but rather an opportunity to improve in two key areas. First commit organization, to have a better view of the contents of a PR with just a look, encouraging developers to write clear, descriptive commit messages and keep their commits well-organized would make code reviews more efficient and help maintain a cleaner project history. Second, the branching strategy; it’s often unclear where branches should originate, where pull requests should be targeted, or how forks should be handled, this lack of structure makes the project history harder to follow and can complicate collaboration and troubleshooting.
No. It is better if developer provide a good commit message. But actually, a committer must must write a correct commit message at merge.
No. It is better if developer provide a good commit message. But actually, a committer must must write a correct commit message at merge.
I agree 100% Those practices should encourage good written commit messages.
1.- What is the problem of current development process? It is not necessarily a problem, but rather an opportunity to improve in two key areas. First commit organization, to have a better view of the contents of a PR with just a look, encouraging developers to write clear, descriptive commit messages and keep their commits well-organized would make code reviews more efficient and help maintain a cleaner project history. Second, the branching strategy; it’s often unclear where branches should originate, where pull requests should be targeted, or how forks should be handled, this lack of structure makes the project history harder to follow and can complicate collaboration and troubleshooting.
No. It is better if developer provide a good commit message. But actually, a committer must must write a correct commit message at merge.
I agree too, but having a convention should encourage the best practices to provide good messages, plus this will also create a better organization of the names of the branches, making it more intuitive with a naming convention.
I agree too, but having a convention should encourage the best practices to provide good messages, plus this will also create a better organization of the names of the branches, making it more intuitive with a naming convention.
What is the relationship between naming convention of branch and good commit message? I cannot understand at all.
My question is area of "naming convention of branch". How wide? In this repository or forked private repository?
Anyway, it doesn't make sense to me on both.
In this repository -> Branch shall be created only for released branch and head, and all of branches are well managed only by committers. I don't think classed repository name is efficient at all.
Both -> It is not a good thing to force branch name on a private repository. Anyway contributor shall open a PR for change. I believe contributor need to describe a good description for their change, do not rely on a branch name.
Anyway, I want to reduce committers. Now there are too many team members on this project because of only GDL guys. I just want to have only REAL committers on this project.