[gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow
Michał Górny posted on Tue, 25 Jul 2017 10:05:06 +0200 as excerpted: > ==Backwards Compatibility== > Most of the new policy will apply to the commits following its approval. > Backwards compatibility is not relevant there. s/Backwards/Backward/ (both header and body) "Backwards" is a regionalism I too have problems with (as a native USian with time in the former Crown colony Kenya and exposure to various European and Asian as well as widely dispersed USian usage. According to the wictionary entry, "backward" is strictly speaking the adjective in British English, "backwards" the adverb, while in the US, the usage is more flexible/regional and may be reversed. But (when I catch myself) I always try to use "backward", because the addition of the terminating "s" adds no meaning and has come to sound like "hick-speak" to my ear. Regardless, in this instance "backward" is used as an adjective, so the stricter "backward" should sound find to the British ear, while being at least flexibly tolerated to the American ear even if their particular region reverses it. (Besides, "backwards compatibility" sounds... like something my car lacked when I was trying to teach someone to drive, after they jammed the transmission in reverse while going forward. Hmm... Maybe I favor the -s form as adverb more than I thought. =:^) > One particular point that affects commits retroactively is the OpenPGP > signing. However, it has been an obligatory requirement enforced by the > infrastructure since the git switch. Therefore, all the git history > conforms to that. -- Duncan - List replies preferred. No HTML msgs. "Every nonfree program has a lord, a master -- and if you use the program, he is your master." Richard Stallman
[gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow
Michał Górny posted on Tue, 25 Jul 2017 10:05:06 +0200 as excerpted: > ===Commit messages=== [...] > Historically, Gentoo has been using a few tags starting with X- > . However, this practice was abandoned once it has been pointed > out that git does not enforce any standard set of tags, and therefore > indicating non-standard tags is meaningless. Thanks for this historical note. I hadn't noticed, but if I had, I might have found the usage and then abandonment confusing, and this clears it up. =:^) > Gentoo developers are still frequently using Gentoo-Bug tag, s/developers are still frequently using/developers still frequently use/ The (past and continuing) tense that you're (apparently) trying to use, while common in other languages, isn't one English treats separately. > sometimes followed by Gentoo-Bug-URL. Using both > simultaneously is meaningless (they are redundant), and using the former > has no advantages over using the classic #nn form in the > summary or the body. -- Duncan - List replies preferred. No HTML msgs. "Every nonfree program has a lord, a master -- and if you use the program, he is your master." Richard Stallman
[gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow
Michał Górny posted on Tue, 25 Jul 2017 10:05:06 +0200 as excerpted:
> ===Splitting commits===
> Git commits are lightweight, and the developers are encouraged to split
> their commits to improve readability and the ability of reverting
> specific sub-changes. When choosing how to split the commits, the
> developers should consider the following three rules:
> # Use atomic commits — one commit per logical change.
> # Split commits at logical unit (package, eclass, profile…) boundaries.
> # Avoid creating commits that are 'broken' — e.g. are incomplete, have
> uninstallable packages.
(Without commenting on the technical specifics, particularly in the
examples, only nitpicking grammar here...)
Two instances of "the developers": Should be "the developer" (singular),
or "developers" (plural, no "the"), your choice. Note that in the first
usage, if the singular "the developer" is chosen, the following "are" and
"their" will need changed to singular as well.
(Of course then there's the question of his/her or a controversial usage
of singular "their" to remain gender neutral, so plural "developers" may
be best there, nicely avoiding the secondary controversy. FWIW, the
appropriateness of singular they/their to avoid gender specificity is a
current topic of debate in linguistic circles, but is "languagelog approved"
at least, citing usage by respected authors going back over a century, and
seems to be on the way toward wider acceptance. YMMV, but it's easy enough
to avoid the entire question here, with consistent plural usage.)
> It is technically impossible to always respect all of the three rules,
s/all of the three rules,/all three rules/
(Note omission of the comma too.)
> so developers have to balance between them at their own discretion. Side
> changes that are implied by other change (e.g. revbump due to some
> change) should be included in the first commit requiring them. Commits
> should be ordered to avoid breakage, and follow logical ordering
> whenever possible.
>
> Examples:
> * When doing a version bump, it is usually not reasonable to split every
> necessary logical change into separate commit since the interim commits
s/into separate commit/into separate commits/
... but that's still slightly uncomfortable due to ambiguous plurality
agreement. Maybe...
"into its own commit"
> would correspond to a broken package. However, if the package has a live
> ebuild, it ''might'' be reasonable to perform split logical changes on
> the live ebuild, then create a release as another logical step.
> * When doing one or more changes that require a revision bump, bump the
> revision in the commit including the first change. Split the changes
> into multiple logical commits without further revision bumps — since
> they are going to be pushed in a single push, the user will not be
> exposed to interim state.
> * When adding a new version of a package that should be masked, you can
> include the {{Path|package.mask}} edit in the commit adding it.
> Alternatively, you can add the mask in a split commit ''preceding'' the
> bump.
> * When doing a minor change to a large number of packages, it is
> reasonable to do so in a single commit. However, when doing a major
> change (e.g. a version bump), it is better to split commits on package
> boundaries.
--
Duncan - List replies preferred. No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master." Richard Stallman
[gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow
Michał Górny posted on Tue, 25 Jul 2017 10:05:06 +0200 as excerpted: > ==Specification== > ===Branching model=== > The main branch of the Gentoo repository is the master > branch. All Gentoo developers push their work straight to the master > branch, provided that the commits meet the minimal quality standards. > The master branch is also used straight for continous user repository > deployment. s/continous/continuous/ > Since multiple developers work on master concurrently, they may be > required to rebase multiple times before being able to push. Developers > are requested not to use workflows that could prevent others from > pushing, e.g. pushing single commits frequently instead of staging them > and using a single push. This is unclear as to which of the two behaviors is encouraged vs. discouraged. Maybe just add an an explicit "(encouraged)" and "(discouraged)" by each as appropriate? > Developers can use additional branches to facilitate review and testing > of long-term projects of larger scale. However, since git fetches all > branches by default, they should be used scarcely. For smaller projects, > local branches or repository forks are preferred. Nit-picking/quibble: "Can" vs. "may": While "can" is perfectly appropriate as used here in informal settings, "may" is more formal (with "can" reserved for whether it's technically possible, not at issue here or it wouldn't need mentioned, while "may" indicates it's approved/recommended, there's a child's game, "Mother may I", that I recall reinforcing this when I was young). Since this is intended as a GLEP it's arguably quite formal and "may" /may/ be more appropriate, thus my mention of the issue altho either should be well understood and "can" would be entirely appropriate if the context isn't considered quite that formal. Entirely a judgment call. > Unless stated otherwise, the rules set by this specification apply to > the master branch only. The development branches can use relaxed rules. Can/may... There may be other uses I won't mention but if you decide it's worth changing at all, a search and evaluate usage may be worth it. > Rewriting history (i.e. force pushes) of the master branch is forbidden. -- Duncan - List replies preferred. No HTML msgs. "Every nonfree program has a lord, a master -- and if you use the program, he is your master." Richard Stallman
[gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow
Michał Górny posted on Tue, 25 Jul 2017 10:05:06 +0200 as excerpted: > ==Motivation== > Although the main Gentoo repository is using git for two years already, > developers still lack official documentation on how to use git > consistently. Most of the developers learn spoken standards from others > and follow them. This eventually brings consistency to some extent but > is suboptimal. Furthermore, it results in users having to learn things > the hard way instead of having proper documentation to follow. Just a couple grammar fixes: First sentence: s/repository is using git/repository has been using git/ Second: s/Most of the developers/Most developers/ -- Duncan - List replies preferred. No HTML msgs. "Every nonfree program has a lord, a master -- and if you use the program, he is your master." Richard Stallman
Re: [gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow
On śro, 2017-07-26 at 19:05 +0200, Kristian Fiskerstrand wrote: > On 07/25/2017 02:28 PM, Michael Palimaka wrote: > > Does a bug # really need to always be in the summary line? It can eat > > valuable characters and tags which are pretty popular are equally valid IMO. > > I would prefer the summary to be informative without having bug ID at > all. Summary should describe the change ,not only "fixes XXX", the bug > reference belongs in body (tags) > I guess I didn't say it verbosely but this obviously should be the case. The bug no is just a cherry at the top. Of course if you can't spare 6 characters, you don't have to put it there. -- Best regards, Michał Górny signature.asc Description: This is a digitally signed message part
Re: [gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow
On 07/26/2017 10:05 AM, Kristian Fiskerstrand wrote: > On 07/25/2017 02:28 PM, Michael Palimaka wrote: >> Does a bug # really need to always be in the summary line? It can eat >> valuable characters and tags which are pretty popular are equally valid IMO. > > I would prefer the summary to be informative without having bug ID at > all. Summary should describe the change ,not only "fixes XXX", the bug > reference belongs in body (tags) > +1. I tend to add bug numbers in my summary, but it makes it very challenging to put something meaningful into the remaining characters. We already put 'category/pkg:' or 'dir/file:' for a prefix. Adding 6 or 7 characters to that already considerable deficit cuts ~15% of git's recommended 50 characters, or 10% of our proposed 70. Pushing this out to a tag -- and standardizing it -- will only improve maintenance and speed up our onboarding process. "Bug: xx" isn't my favorite since it requires tooling to actually visit said bug (and doesn't clarify which bug platform to reference), but a URL uses more bytes and infra may change. It's a tough choice, but if we can find something that fits enough use cases, tooling shouldn't be too difficult to write to make up for it. I already use a `bgo` keyworded shortcut in Pale Moon to make bug searching faster; adding another to navigate straight to a bug wouldn't be much trouble. -- Daniel Campbell - Gentoo Developer OpenPGP Key: 0x1EA055D6 @ hkp://keys.gnupg.net fpr: AE03 9064 AE00 053C 270C 1DE4 6F7A 9091 1EA0 55D6 signature.asc Description: OpenPGP digital signature
Re: [gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow
On Wed, Jul 26, 2017 at 07:05:47PM +0200, Kristian Fiskerstrand wrote: > On 07/25/2017 02:28 PM, Michael Palimaka wrote: > > Does a bug # really need to always be in the summary line? It can eat > > valuable characters and tags which are pretty popular are equally valid IMO. > > I would prefer the summary to be informative without having bug ID at > all. Summary should describe the change ,not only "fixes XXX", the bug > reference belongs in body (tags) > > -- > Kristian Fiskerstrand > OpenPGP keyblock reachable at hkp://pool.sks-keyservers.net > fpr:94CB AFDD 3034 5109 5618 35AA 0B7F 8B60 E3ED FAE3 +1 Given the length restriction and the requirement to include category/package, adding a bug reference doesn't leave much space for a useful description. -- Sam Jorna (wraeth) GnuPG Key: D6180C26 signature.asc Description: Digital signature
Re: [gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow
On 07/25/2017 02:28 PM, Michael Palimaka wrote: > Does a bug # really need to always be in the summary line? It can eat > valuable characters and tags which are pretty popular are equally valid IMO. I would prefer the summary to be informative without having bug ID at all. Summary should describe the change ,not only "fixes XXX", the bug reference belongs in body (tags) -- Kristian Fiskerstrand OpenPGP keyblock reachable at hkp://pool.sks-keyservers.net fpr:94CB AFDD 3034 5109 5618 35AA 0B7F 8B60 E3ED FAE3 signature.asc Description: OpenPGP digital signature
Re: [gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow
On wto, 2017-07-25 at 22:28 +1000, Michael Palimaka wrote: > On 07/25/2017 06:05 PM, Michał Górny wrote: > > Hi, everyone. > > > > There have been multiple attempts at grasping this but none so far > > resulted in something official and indisputable. At the same time, we > > end having to point our users at semi-official guides which change > > in unpredictable ways. > > > > Here's the current draft: > > https://wiki.gentoo.org/wiki/User:MGorny/GLEP:Git > > This looks really nice, thanks for working on it. > > > * When doing a minor change to a large number of packages, it is > > reasonable to do so in a single commit. However, when doing a major > > change (e.g. a version bump), it is better to split commits on package > > boundaries. > > In some cases we do prefer to make major changes on a set of related > package all in one commit. For example, we always bump the 240+ KDE > Applications collection together because that's how it's released. It's merely a recommendation. I don't want to cover every single use case because that would be insane. I'm already worried I've covered too many cases for people to read it all. > > ===Commit messages=== > > A standard git commit message consists of three parts, in order: a > > summary line, an optional body and an optional set of tags. The parts > > are separated by a single empty line. > > > > The summary line is included in the short logs (git log -- > > oneline, gitweb, GitHub, mail subject) and therefore should > > provide a short yet accurate description of the change. The summary line > > starts with a logical unit name, followed by a colon, a space and a > > short description of the most important changes. If a bug is associated > > with a change, then it should be included in the summary line as > > #nn or likewise. The summary line must not exceed 69 > > characters, and must not be wrapped. > > Does a bug # really need to always be in the summary line? It can eat > valuable characters and tags which are pretty popular are equally valid IMO. Tags don't appear on 'git log --oneline' or cgit/gitweb shortlog. If you are groking through multiple bugs, it is more convenient if you can find the bug no straight away. > > ** Bug: https://bugs.gentoo.org/NN;; — to > > reference a bug, > > ** Closes: https://github.com/gentoo/gentoo/pull/ > ki>; — to automatically close a GitHub pull request, > > ** Fixes: https://bugs.gentoo.org/NN;; — > > to indicate a fixed bug, > > grepping the git log shows that 'Gentoo-bug' is much more common than > plain 'Bug'. 'Fixes' is hardly used at all, and I think it's a bit > confusing to use this for bugs as well as commits. 'Fixes' is the original tag used by other projects. 'Bug' is shorter than 'Gentoo-bug' and avoids repeating the obvious. Much like we do not have 'Gentoo-signed-off-by', 'Gentoo-thanks-to' and so on, having 'Gentoo-bug' is equally silly. Furthermore, full URLs should be used with tags. If you are already using tags (i.e. long form), don't do it half-way and put useless digits there. Put URL that will be interpreted by practically all visual git tools written ever. > > a few branches on the repository, and did not maintain them. The Infra > > had to query the developers about the state of the branches and clean > > them up. > > Should 'The Infra' be 'The Infra team' or just 'Infra'? Yes, thanks. > > > Gentoo developers are still frequently using Gentoo-Bug tag, > > sometimes followed by Gentoo-Bug-URL. Using both > > simultaneously is meaningless (they are redundant), and using the former > > has no advantages over using the classic #nn form in the > > summary or the body. > > I agree that using both is redundant, but I don't agree with > discouraging or banning the use of 'Gentoo-bug'. If someone prefers to > use it so it sits nicely with the other tags why stop them? I'm not stopping anyone. This is merely a suggestion. Encouraging two different tags for the same thing would be confusing to users. -- Best regards, Michał Górny signature.asc Description: This is a digitally signed message part
[gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow
On 07/25/2017 06:05 PM, Michał Górny wrote: > Hi, everyone. > > There have been multiple attempts at grasping this but none so far > resulted in something official and indisputable. At the same time, we > end having to point our users at semi-official guides which change > in unpredictable ways. > > Here's the current draft: > https://wiki.gentoo.org/wiki/User:MGorny/GLEP:Git This looks really nice, thanks for working on it. > * When doing a minor change to a large number of packages, it is > reasonable to do so in a single commit. However, when doing a major > change (e.g. a version bump), it is better to split commits on package > boundaries. In some cases we do prefer to make major changes on a set of related package all in one commit. For example, we always bump the 240+ KDE Applications collection together because that's how it's released. > ===Commit messages=== > A standard git commit message consists of three parts, in order: a > summary line, an optional body and an optional set of tags. The parts > are separated by a single empty line. > > The summary line is included in the short logs (git log -- > oneline, gitweb, GitHub, mail subject) and therefore should > provide a short yet accurate description of the change. The summary line > starts with a logical unit name, followed by a colon, a space and a > short description of the most important changes. If a bug is associated > with a change, then it should be included in the summary line as > #nn or likewise. The summary line must not exceed 69 > characters, and must not be wrapped. Does a bug # really need to always be in the summary line? It can eat valuable characters and tags which are pretty popular are equally valid IMO. > ** Bug: https://bugs.gentoo.org/NN; — to > reference a bug, > ** Closes: https://github.com/gentoo/gentoo/pull/ ki>; — to automatically close a GitHub pull request, > ** Fixes: https://bugs.gentoo.org/NN; — > to indicate a fixed bug, grepping the git log shows that 'Gentoo-bug' is much more common than plain 'Bug'. 'Fixes' is hardly used at all, and I think it's a bit confusing to use this for bugs as well as commits. > a few branches on the repository, and did not maintain them. The Infra > had to query the developers about the state of the branches and clean > them up. Should 'The Infra' be 'The Infra team' or just 'Infra'? > Gentoo developers are still frequently using Gentoo-Bug tag, > sometimes followed by Gentoo-Bug-URL. Using both > simultaneously is meaningless (they are redundant), and using the former > has no advantages over using the classic #nn form in the > summary or the body. I agree that using both is redundant, but I don't agree with discouraging or banning the use of 'Gentoo-bug'. If someone prefers to use it so it sits nicely with the other tags why stop them?
