On 30 January 2013 00:22, Adam Spiers
<address@hidden> wrote:
Whilst the procedure of marking an issue as fixed, with an additional
Fixed_mm_MM_ss label, is briefly mentioned at the end of the "Issue
classification section" in the Contributor's Guide:
http://lilypond.org/doc/v2.17/Documentation/contributor/issue-classification
it is slightly misleading, and also omits important details:
- Fixed_mm_MM_ss suggests fixed width, e.g. Fixed_02_17_01, but this
is not the case. It would be better to call it Fixed_X_Y_Z.
- What's the correct value of X, Y, and Z? (Answer is presumably
that they come from MAJOR_VERSION, MINOR_VERSION, and PATCH_LEVEL
in $LILYPOND_GIT/VERSION)
Yes although I am not sure, do we call 'Z' in your example 'patch level'? It might be better to give an example as well.
Fixed_2_17_11
If you are editing this part it might be nice to explain how to find out which values (esp for Z) to use. I.e. I check the last Tag in URI '
http://git.savannah.gnu.org/gitweb/?p=lilypond.git' whereas they may be better ways. Aiming parts of the CG at the correct audience with the correct level of 'technical description based on their ability' is a bit of an art especially for people like myself, who know just enough to be dangerous.
- Are developers supposed to mark the issue as fixed immediately
after pushing the corresponding patch series to staging, or should
they first wait for the tests to automatically advance master?
The assumption is that once someone has pushed to Staging it should be considered 'fixed', else I think you would cause extra irritation where the dev has to check back again, make sure it is in master and then update the tracker. It is better in my opinion to assume fixed once it has been pushed to staging so the dev can update the tracker labels _at the same time_ they put in the commit reference to help the bugsquad/verifiers.
The patch ought (but not always) to have some reference to the tracker so that in the unlikelycase it gets pushed and breaks master nonetheless there is an easy way to go back and set the tracker to 'needs_work' once it has been reverted (or whatever ends up being done).
Additionally, the above information still needs to be explicitly
referenced from the two[1] places where pushing to staging is
documented:
http://lilypond.org/doc/v2.17/Documentation/contributor/git-for-the-impatient
http://lilypond.org/doc/v2.17/Documentation/contributor/pushing-to-staging
I think it would be better to reference via links back to the 'Issue
classification' section, rather than have the same information
duplicated three times.
I have no strong feelings either way. I think the design of the CG is that someone should be able to pick it up and based on their abilities not have to jump about the doc to find things they need (again depending on their ability and requirement). If that means repeating things then I don't necessarily think that is a bad thing as long as what is repeated is either copied verbatim or perhaps rewritten for the audience that the section is referring to (i.e. experienced devs vs non-experienced devs).
Obviously this doesn't apply to the other documents, the CG is always a work-in-progress where we don't tend to mind chatty style, loose formatting of instructions and so on compared to say the Notation Reference.
Thanks,
Adam
[1] Speaking of duplication, why do we document the procedure for
pushing to staging twice? The version in 'Git for the impatient' is
hardly any shorter than the full version in 'Pushing to staging', and
violating the DRY rule increases the maintenance burden and also risks
information becoming out of date in one of the two places. Should
impatient git users even be allowed to push to staging?
As long as someone who is not familiar with GIT or doesn't do programming (like me) doesn't have to navigate through something designed for people who are (for example) going to create personal seerate branches with all the popping and pushing and rebasing malarky that I don't do or need to know to do what I do for LP.
James