Git branching strategy

[joapuiib]

I'm writting this discussion directly to @jaywhj as the owner and mantainer of this repository.

I'm no Git expert and I know branching strategies are very personal. Nevertherless, I think the current approach can be improved.

Right now, the master branch looks like this.

This are the aspects that I think can be improved:

• Mantain a linear history: if you go back on the history on the repository, you can see that it is linear and tidier.

  Example old history

  

• Don't merge unecessary commits: As you can see in the history, after Feature: Modularize Admonition CSS for easier extensibility #16 or Docs: Update development setup #18 has been merged, all commits in this branch have been merged too, which might be unnecessary.

---

My proposal

In order to improve the previousle stated aspects, I propose the following strategy.

• Require master to be linear. In this sense, it is possible to include a Ruleset to enforce a branch is linear.

  • Also, care when pulling with git pull. By default, this create a merge commit. A rebase can be used by git pull --rebase in order to mantain linear history.

• Always merge squash pull requests: This will create a single commit in master with all changes proposed on the working branch and no merge commit will be created.

  • In the repository settings, you can disable merge and rebase merging for PR and only allow the merge squash method.

Change develop by master in the diagram.

---

Extra: renaming master to main

• Regarding Git and Branch Naming
• https://github.com/github/renaming

[DevTwilight]

I think @joapuiib is right. As a documentation writer and a code contributor to many projects, I would prefer a squash merge since it combines all my commits into a single, meaningful commit and keeps the history clean for future contributions.

[jaywhj]

@joapuiib

Thanks for the detailed suggestion — this is very helpful.

I agree with your points about maintaining a linear history and avoiding unnecessary commits. The current history has indeed become less tidy compared to earlier stages.

I’ll update the repository workflow accordingly:

• Use squash merge for all pull requests
• Disable merge commits and rebase merging in repository settings
• Keep the master branch strictly linear going forward

For existing history, I’ll leave it as-is to avoid rewriting commits, but all future changes will follow this strategy.

Appreciate you taking the time to write this up — this will definitely improve the long-term maintainability of the project.

[jaywhj]

@joapuiib I'm now renaming master to main.

[joapuiib]

Thanks for taking the suggestions into consideration 😁