@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
Document syntax in commit messages which causes effects
Summary:
Docs are great. They document things you may have never heard of. Occasionally you even find the relevant docs and may go read them if time permits.
Fixes T15153
Test Plan:
* Apply patch
* Run `./bin/diviner generate`
* Look at http://phorge.localhost/book/flavor/article/writing_reviewable_code/#write-sensible-commit-messages and http://phorge.localhost/book/phorge/article/arcanist_diff/
Reviewers: O1 Blessed Committers, mainframe98
Reviewed By: O1 Blessed Committers, mainframe98
Subscribers: mainframe98, tobiaswiese, valerio.bozzolan, Matthew, Cigaryno
Maniphest Tasks: T15153
Differential Revision: https://we.phorge.it/D26121
+25
-2
+22
src/docs/flavor/writing_reviewable_code.diviner
+22
src/docs/flavor/writing_reviewable_code.diviner
···
126
126
useful for the reviewer and for anyone trying to understand the change after the
127
127
fact.
128
128
129
+
== Referencing Other Objects ==
130
+
129
131
An easy way to explain //why// is to reference other objects
130
132
(bugs/issues/revisions) which motivate the change.
131
133
134
+
Commit messages support special syntax you can use in your commit message to
135
+
cause effects on related items:
136
+
137
+
- `Ref T123`: Attach a revision or a commit to a task. You can also specify
138
+
several tasks, optionally using commas: `Ref T123 T124` or `Ref T123, T124`.
139
+
- `Fixes T123`: Close a task when pushing a commit.
140
+
- `Reverts rXabcdef`: Mark a commit as reverting something.
141
+
- `Depends on D123`: Mark a revision as depending on another revision.
142
+
143
+
Similar syntax exists for each status you may want to set on a related task.
144
+
Define the syntax to cause an effect via the `prefixes` key of a task status
145
+
configured via the configuration option `maniphest.statuses`.
146
+
147
+
You can also attach a revision to a task `T123` by diffing it from a branch name
148
+
like `T123-newfeature` with `arc`.
149
+
150
+
== Test Plans ==
151
+
132
152
Differential also includes a "Test Plan" field which is required by default.
133
153
There is a detailed description of this field in @{article:Differential User
134
154
Guide: Test Plans}. You can make it optional or disable it in the configuration,
135
155
but consider adopting it. Having this information can be particularly helpful
136
156
for reviewers.
157
+
158
+
== Social Constructs ==
137
159
138
160
Some things that people sometimes feel strongly about but which are probably not
139
161
really all that important in commit messages include:
+3
-2
src/docs/user/userguide/arcanist_diff.diviner
+3
-2
src/docs/user/userguide/arcanist_diff.diviner
···
143
143
144
144
- squashing or merging changes from a feature branch into a master branch
145
145
(if relevant);
146
-
- formatting a good commit message with all the information from Differential;
147
-
and
146
+
- formatting a good commit message (see //Write Sensible Commit Messages// in
147
+
@{article:Writing Reviewable Code}) with all the information from
148
+
Differential; and
148
149
- automatically closing the revision.
149
150
150
151
You don't need to use any of these workflows: you can just run `git push`,