docs: contributing: add exercpt about rewriting branches#159
docs: contributing: add exercpt about rewriting branches#159JGBSouza wants to merge 1 commit intokworkflow:unstablefrom
Conversation
lorenzoberts
left a comment
lorenzoberts
left a comment
There was a problem hiding this comment.
Hey @JGBSouza, thanks for the contribution! Let me know if my comments make sense.
Besides that, regarding the commit message, i think it's better for us to start it by directly saying what the commit does: "This commit adds/..". After that, if you want to add a more "abstract" reflection of the commit importance, or anything not so direct, feel free to do it. You can also add the reference to the issue in the commit itself, not only in the PR. Example
CONTRIBUTING.md
Outdated
|
|
||
| You may find more about it at: [Git Tools: Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) | ||
|
|
||
| #### What are we talking about |
There was a problem hiding this comment.
| #### What are we talking about | |
| #### What are we talking about? |
CONTRIBUTING.md
Outdated
|
|
||
| #### What are we talking about | ||
|
|
||
| When working on a pull request for patch-hub, you will often re-evaluate something you already committed: fix or refactor an implementation, split a commit into smaller, self-contained pieces, reorder commits for clarity, and more. In these cases, we recommend rewriting the branch history (using interactive rebase git rebase -i and git commit --amend) rather than stacking fix commits on top of your branch. |
There was a problem hiding this comment.
| When working on a pull request for patch-hub, you will often re-evaluate something you already committed: fix or refactor an implementation, split a commit into smaller, self-contained pieces, reorder commits for clarity, and more. In these cases, we recommend rewriting the branch history (using interactive rebase git rebase -i and git commit --amend) rather than stacking fix commits on top of your branch. | |
| When working on a pull request for patch-hub, you will often re-evaluate something you already committed: fix or refactor an implementation, split a commit into smaller, self-contained pieces, reorder commits for clarity, and more. In these cases, we strongly recommend rewriting the branch history (using interactive rebase git rebase -i and git commit --amend) rather than stacking new commits on top of your branch. |
CONTRIBUTING.md
Outdated
|
|
||
| When working on a pull request for patch-hub, you will often re-evaluate something you already committed: fix or refactor an implementation, split a commit into smaller, self-contained pieces, reorder commits for clarity, and more. In these cases, we recommend rewriting the branch history (using interactive rebase git rebase -i and git commit --amend) rather than stacking fix commits on top of your branch. | ||
|
|
||
| #### Why is this important |
There was a problem hiding this comment.
| #### Why is this important | |
| #### Why is this important? |
CONTRIBUTING.md
Outdated
|
|
||
| #### Why is this important | ||
|
|
||
| Rewriting commits helps ensure the pull request shows only the final, intended changes. This improves reviewability and long-term maintainability by avoiding a noisy trail of intermediate fixes, making it easier for reviewers to understand the final result without tracking every small adjustment. |
There was a problem hiding this comment.
There is a justification for why it improves reviewability but not why it improves long-term maintainability. I think you should also mention the benefits considering the git history, project versioning, etc.
This commit adds a new subsection, “Rewriting Branches”, to the Pull Request Guidelines in the contributing.md file. The new section explains what branch rewriting is, why it’s essential for contributing to the Patch Hub project, and links to the official Git documentation for more detailed guidance. Rewriting branches is a key skill in Patch Hub’s contribution workflow, helping ensure pull requests remain clean, focused, and easy to review. It also maintains a meaningful Git history, which improves long-term maintainability and version tracking. Closes kworkflow#151 Signed-off-by: JGBSouza <joaosouzaaa12@usp.br>
JGBSouza
force-pushed
the
docs/add_excerpt_rewriting_branches
branch
from
69aae10 to
cfcaade
Compare
Hi Lorenzo, fixed this pull request and the commit message! |
lorenzoberts
left a comment
lorenzoberts
left a comment
There was a problem hiding this comment.
Thanks @JGBSouza. Commit merged into unstable branch. Will close this PR.
2 participants
This commit adds a new subsection, “Rewriting Branches”, to the Pull Request Guidelines in the contributing.md file.
The new section explains what branch rewriting is, why it’s essential for contributing to the Patch Hub project, and
links to the official Git documentation for more detailed guidance.
Rewriting branches is a key skill in Patch Hub’s contribution workflow, helping ensure pull requests remain clean,
focused, and easy to review. It also maintains a meaningful Git history, which improves long-term maintainability and
version tracking.
Closes #151