Skip to content

Commit 122133b

Browse files
committed
docs: add explanation on commits and commit messages
1 parent e215d66 commit 122133b

File tree

1 file changed

+23
-1
lines changed

1 file changed

+23
-1
lines changed

contributing/workflow.md

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,16 +139,38 @@ Your local changes need to be *committed* to save them in your local
139139
repository. This is where [contribution signing](./signing.md) comes
140140
in.
141141

142+
Now we don't have detailed rules on commits and its messages. But
143+
[atomic commit](https://en.wikipedia.org/wiki/Atomic_commit#Atomic_commit_convention) is recommended.
144+
Keep your commits atomic. One commit for one change.
145+
146+
There are some references for writing good commit messages:
147+
148+
- [Git Best Practices — AFTER Technique - DZone DevOps](https://dzone.com/articles/git-best-practices-after-technique-1)
149+
- [Semantic Commit Messages](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716)
150+
- [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
151+
152+
If there are intermediate commits that are not meaningful to the overall PR,
153+
such as "Fix error on style guide", "Fix phpstan error", "Fix mistake in code",
154+
and other related commits, you can squash your commits so that we can have a clean commit history.
155+
But it is not a must.
156+
157+
### Commit messages
158+
159+
Commit messages are expected to be descriptive of **why** and what you changed specifically.
160+
Commit messages like "Fixes #1234" would be asked by the reviewer to be revised.
161+
142162
You can have as many commits in a branch as you need to "get it right".
143163
For instance, to commit your work from a debugging session:
144164

145165
```console
146166
> git add .
147-
> git commit -S -m "Find and fix the broken reference problem"
167+
> git commit -S -m "Fix the broken reference problem"
148168
```
149169

150170
Just make sure that your commits in a feature branch are all related.
151171

172+
### When you work on two features
173+
152174
If you are working on two features at a time, then you will want to
153175
switch between them to keep the contributions separate. For instance:
154176

0 commit comments

Comments
 (0)