develooper Front page | perl.perl5.porters | Postings from February 2018

Documenting commits and changes

Thread Next
Sawyer X
February 16, 2018 22:33
Documenting commits and changes
Message ID:
With the upcoming dev release, I think it's time to approach this topic.
It was raised in the last P5H core hackathon but remained unresolved and
I would like to approach it now.

Currently the situation is:

* Commits are made on blead or in a branch.
* Branches are merged with fast forwarding, making them equivalent to
being made on blead.
* Some commits include documenting changes in perldelta.
* Some commits are solely the perldelta update.
* Some commits do not require a perldelta update.
* Some commits do require it but do not include it in either the commit
or following commits.
* Release Managers need to check every commit[1] to verify whether it
needs documentation, and if so whether it was, and if so, how.
* Release Managers might send emails to commit authors to understand:
Should something be committed, and if so, how.

There are several ways to approach it. Here are the two obvious ways I
can come up:

Option 1. Each commit done in a branch when the last commit is perldelta
update, if necessary. Branches are merged with "--no-ff" to make sure we
see the branch.[2]

This is my personal preference. It's what I do in other projects and it
makes it clear to track each commit to a branch of feature/fixes and the
last one contains a documentation update. If it's not there, you don't
need to document it. The difficulty here is that many small commits
(especially those that do not require documentation) are annoying to do
in a branch and then merge with "--no-ff". We can also just allow any
commit that doesn't require documentation to just be done directly on blead.

Option 2. Commits include a note (like a few letters indicator either in
the summary or in the message) whether they were documented or should
(or shouldn't) be documented. This would at least allow Release Managers
to validate the commits quickly.

This would fit better when a change is still in the making (which I
expect not to be the norm) and a commit could include "perldelta update
forthcoming." One relevant pattern here is Tony's use of commits that
mention they are the perldelta update of <commit ID>.

What do you think of these options? Other suggestions?

[1] This isn't hyperbolic. We need to check every commit.
[2] This also means that "git pull" is run as "git pull
--rebase=preserve" to make sure that a pull doesn't have a conflict and
doesn't remove the branch name.

Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About