docs(contributing)!: clarify use of scopes and breaking changes #150

dharapandya85 · 2025-07-01T12:45:13Z

This updates the "Use Conventional Commits" section to include the proper syntax for scope and breaking changes.

Changes:

Introduced the format : <type>(<scope>)! : <description>
Added a clear example: feat (foo)!: introduce breaking change bar
Linked to the Conventional Commits v1.0.0 specification

This provides clearer guidance for contributors writing commit messages.

dharapandya85 · 2025-07-01T12:53:43Z

Hello, this PR improves the documentation on Conventional Commits by clarifying the use of scopes and breaking changes. Let me know if any adjustments are needed. Thanks!

davidbtadokoro

Hey @dharapandya85 and thank you for the great effort! Documentation is one of the most overlooked things and CONTRIBUTING.md has quite some problems. I left some comments inline, but you should also check:

The commit message title, contains the breaking changes ! indicator, which doesn't proceed
You should always add a commit message body

[UPDATES]:

You can and should drop the second commit (the merge one)
To better see the inline comments below, go into the commits tab and go commit by commit (in this case, the only one commit, not considering the merge)

CONTRIBUTING.md

davidbtadokoro · 2025-07-09T15:40:57Z

CONTRIBUTING.md

-6. [Pull Request Guidelines](#pull-request-guidelines)
-7. [Issue Reporting](#issue-reporting)
-8. [Communication](#communication)
+3. [Development Cycle and Branches](#development-cycle-and-branches)


Same as the comment above. This change has merit, but it shouldn't go in this commit

davidbtadokoro · 2025-07-09T15:41:59Z

CONTRIBUTING.md

@@ -104,9 +104,20 @@ Commit contents, in other words, the changes the commit introduce should:
 - Not destabilize the compilation, so `cargo build` shouldn't fail.
 - Not fail in CI jobs.

-### Use Conventional Commits
+## Use Conventional Commits


I don't think we should elevate this subsection to a section as it makes sense to keep it under the "Commit Guidelines" section

davidbtadokoro · 2025-07-09T15:46:33Z

CONTRIBUTING.md

-5. [Commit Guidelines](#commit-guidelines)
-6. [Pull Request Guidelines](#pull-request-guidelines)
-7. [Issue Reporting](#issue-reporting)
-8. [Communication](#communication)


Same as the comment above. This change has merit, but it shouldn't go in this commit

davidbtadokoro · 2025-07-09T15:46:53Z

CONTRIBUTING.md

+4. [Commit Guidelines](#commit-guidelines)
+5. [Pull Request Guidelines](#pull-request-guidelines)
+6. [Issue Reporting](#issue-reporting)
+7. [License](#license)


Same as the comment above. This change has merit, but it should go in this commit

davidbtadokoro · 2025-07-09T15:47:05Z

CONTRIBUTING.md

+5. [Pull Request Guidelines](#pull-request-guidelines)
+6. [Issue Reporting](#issue-reporting)
+7. [License](#license)
+


Also, no need for this extra line

davidbtadokoro · 2025-07-09T15:48:53Z

CONTRIBUTING.md

+`patch-hub` follows the use of [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification. Commit message use the format:
+`<type>(<scope>)!: <description>`
+
+- `type`: kind of change (e.g., `feat`,`fix`,`docs`)
+-  `scope`: optional module or section of the codebase
+- `!`: indicates a **breaking change**
+- `description`: short summary of the change
+
+Example:
+feat(foo)!: introduce breaking change bar

-`patch-hub` follows the use of [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) wherein you indicate the type of change you're making at the start with a label, followed by a scope (optional, since the project is still small), and then the commit message after a colon.
+For more, see [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) 


Strange... I see you've adapted the original line 109 to not be redundant, but by going to the branch of your PR, for some reason, this duplication happens:

dharapandya85 · 2025-07-10T12:25:24Z

Thank you, @davidbtadokoro, for the review. I would like to clarify some doubts regarding:
1)How should the commit message and body message be structured if the section of the table of contents needs to be changed? It must be mentioned in the commit message.
2) No redundant lines should be included.
3) Regarding the correct format for breaking changes.
If it's needed, I would like to correct the above or open a new PR. Please let me know how to proceed further, and I will update the CONTRIBUTING.md accordingly. Please review the changes I made in docs/conventional-commits-update branch.

davidbtadokoro · 2025-07-10T14:27:09Z

Hey @dharapandya85 and thanks for the feedback!

How should the commit message and body message be structured if the section of the table of contents needs to be changed? It must be mentioned in the commit message.

I don't know if I got this right, but you shouldn't change the table of contents in this PR, at least, not in the same commit where you are enforce the use of conventional commits. You could do:

First commit: enforce conventional commits use
Second commit: Remove inexistent sections

About the commit message body, prefer not using bullet points like you did but something like "Because of do " (take note of the imperative mode like you did in the title). A good message on commit messages (not just for patch-hub) is this one.

No redundant lines should be included.

This seems like a bug on GitHub, but if you go to the CONTRIBUTING.md of your branch (check it here) the part where you remove the

patch-hub follows the use of [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) wherein ...

is still there...

Regarding the correct format for breaking changes.

The form of breaking changes is like you've explained. I just raised the point that you've added the ! of breaking changes to the original commit, and this PR doesn't not introduce breaking changes.

If it's needed, I would like to correct the above or open a new PR.

Yes, correct the above in this same PR. Don't open another one 😅

Beyond that, don't forget to address the other two comments I did. Feel free to ping me if you have any more doubts!

dharapandya85 · 2025-07-11T11:50:16Z

Thanks @davidbtadokoro! I have split the commits as suggested, removed the redundant line in CONTRIBUTING.md, removed the nonexistent sections, and corrected message formatting. Could you let me know if any corrections are needed?

davidbtadokoro · 2025-07-11T12:01:23Z

Hi @dharapandya85, and thanks for the update! You've made progress, but there are still things that need to be taken care of.

This may sound weird if you never did it, but instead of adding more commits to your branch, you should always amend them and, if you have more than one commit, you should do a git rebase (this reference is really good for this stuff).

The commit message should have a message body. What I said about the format of it, was that it isn't good to just write it in a checklist format, but you should always add a commit message body.

Beyond that, you didn't address the comment about not elevating the subsection "Convention Commits" to a section (it should still be under commit guidelines). And, taking the opportunity, I don't feel the need to change "Development Workflow" to "Development Cycle and Branches" as this section is about much more than just that (development cycle is about releasing and workflow covers exactly what the section is described).

Again, I am not trying to be snappy, but to show you the correct way to contribute to patch-hub, and, also, to most projects. Thanks for the effort and commitment!

[UPDATE]: Forgot to reinforce that you should drop the merge commit you have in your branch

dharapandya85 · 2025-07-12T07:12:53Z

Thanks @davidbtadokoro for the feedback. I have now added the body to the commit message, didn't change "Development Workflow" to "Development Cycles and Branches", made a subsection of "Conventional Commits" under " Commit Guidelines", as suggested, I amended the commit and rebased the branch. But I had initially dropped the commit message of "merge to unstable" during rebase, and I don't know why it is still visible. Please inform me if I missed anything or if any adjustments are needed for the branch. I would appreciate any further review. or guidance

davidbtadokoro · 2025-07-17T08:50:14Z

Hi @dharapandya85, thanks for the update and sorry for the delay.

My bad if I am communicating badly, but this PR should only contain one commit that implements the change minimally, so you should drop all other commits, and don't have commits like the third and fourth that "revert" the first commit changes (e.g., making "Use Conventional Commits" a section again).

I enforce the importance of you checking and reading about rewriting a branch through this reference. I know I keep hitting on this key, but knowing this stuff is essential to contributing (maybe I will make this a section on the guidelines).

In any case, don't hesitate to ask questions.

dharapandya85 · 2025-07-18T12:28:23Z

Thanks @davidbtadokoro for guidance. I have dropped the commits "enforcing conventional commits use" and "clarifying use of scopes". Please inform me of any other adjustments. Now, the PR has one clean commit.

davidbtadokoro

Hey @dharapandya85, this last update is a progress! You got the point that we need only a single commit. The problems now are:

There are merge conflict artifacts in the commit
The commit itself doesn't clarify the use of scopes and the like (it only adds the mentioned conflict artifacts and repeats sections)
The commit message still has the bullet points format, which, as I mentioned a few times, is not the style we prefer here in patch-hub

We are progressing, but, by now, we have had a lot of review cycles, and would really appreciate if you did things slowly and tried to really grasp the things I am proposing to you. I won't ever negate reviews or feedback; yet, I feel like I am having to keep repeating things I already said...

In short, don't need to rush! Take your time to really understand what I am communicating. Thanks for keeping the work!

davidbtadokoro · 2025-07-18T12:32:08Z

CONTRIBUTING.md

@@ -7,11 +7,19 @@ Thank you for your interest in contributing to `patch-hub`! This document outlin
 1. [Code of Conduct](#code-of-conduct)
 2. [Getting Started](#getting-started)
 3. [Development Workflow](#development-workflow)
+<<<<<<< HEAD


It seems you have pushed a commit with artifacts from a rebase

davidbtadokoro · 2025-07-18T12:32:35Z

CONTRIBUTING.md

 4. [Coding Style](#coding-style)
 5. [Commit Guidelines](#commit-guidelines)
 6. [Pull Request Guidelines](#pull-request-guidelines)
 7. [Issue Reporting](#issue-reporting)
 8. [Communication](#communication)
+=======


Same here about a rebase artifact

davidbtadokoro · 2025-07-18T12:32:42Z

CONTRIBUTING.md

+6. [Issue Reporting](#issue-reporting)
+7. [License](#license)
+
+>>>>>>> 8571767 (docs(contributing): clarify commit guidelines structure)


Same here about a rebase artifact

Update the example commits under the "Use Conventional Commits" section to demonstrate proper usage of scopes and how to indicate breaking changes with the `!` symbol. This improves clarity for contributors and aligns example with expected commit formatting. Signed-off-by: dharapandya85 <[email protected]>

dharapandya85 · 2025-07-22T12:19:56Z

Thank you, @davidbtadokoro, for your efforts and feedback. Sorry for the trouble of reminding me again and again about the body of the commit message. As suggested:

No merge conflicts.
No bulleted points in the commit message.
Mentioned use of breaking scope changes (as the initial purpose of this PR).
I would like to clarify that I should mention the following in the commit message:
Not elevating Conventional Commits and maintaining a subsection of Commit Guidelines.
Not renaming the Development Cycles and Branches section.
Removing the redundant lines.
Resolving merge conflicts.
About the commit message body, does it align with the purpose of the PR, or does it need any changes? or adding a footer.
Again, thanks for the feedback and reviewing the PR.

davidbtadokoro requested changes Jul 9, 2025

View reviewed changes

dharapandya85 force-pushed the docs/conventional-commits-update branch from 969627c to 48a609a Compare July 10, 2025 11:53

dharapandya85 force-pushed the docs/conventional-commits-update branch 2 times, most recently from d8bfd39 to 24e6064 Compare July 11, 2025 11:37

dharapandya85 force-pushed the docs/conventional-commits-update branch 2 times, most recently from 4544429 to 8571767 Compare July 12, 2025 07:00

dharapandya85 force-pushed the docs/conventional-commits-update branch from 8571767 to abbaecb Compare July 18, 2025 12:21

davidbtadokoro requested changes Jul 18, 2025

View reviewed changes

dharapandya85 force-pushed the docs/conventional-commits-update branch from b584e4c to 1f7ae75 Compare July 22, 2025 11:51

docs(contributing)!: clarify use of scopes and breaking changes #150

Are you sure you want to change the base?

docs(contributing)!: clarify use of scopes and breaking changes #150

Uh oh!

Conversation

dharapandya85 commented Jul 1, 2025

Uh oh!

dharapandya85 commented Jul 1, 2025

Uh oh!

davidbtadokoro left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dharapandya85 commented Jul 10, 2025

Uh oh!

davidbtadokoro commented Jul 10, 2025

Uh oh!

dharapandya85 commented Jul 11, 2025

Uh oh!

davidbtadokoro commented Jul 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dharapandya85 commented Jul 12, 2025

Uh oh!

davidbtadokoro commented Jul 17, 2025

Uh oh!

dharapandya85 commented Jul 18, 2025

Uh oh!

davidbtadokoro left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dharapandya85 commented Jul 22, 2025

Uh oh!

Uh oh!

davidbtadokoro left a comment •

edited

Loading

davidbtadokoro commented Jul 11, 2025 •

edited

Loading