[gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 19514 bytes --]

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

The basic idea is that the GLEP provides basic guidelines for using git,
and then we write a proper manual on top of it (right now, all the pages
about it end up as a mix of requirements and a partial git manual).

What do you think about it? Is there anything else that needs being
covered?

Copy of the markup for inline comments follows.

---

{{GLEP
|Number=xx
|Title=Gentoo Git Workflow
|Type=Standards Track
|Status=Draft
|Author=Michał Górny <mgorny@gentoo.org>
}}

==Abstract==
This GLEP specifies basic standards and recommendations for using git
with the Gentoo ebuild repository. It covers only Gentoo-specific
policies, and is not meant to be a complete guide.

==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.

There were a few attempts to standardize git use over the time. Most
noteworthy are [[Gentoo git workflow]] and [[Gentoo GitHub]] articles.
However, they are not any kind of official standards, and they have too
broad focus to become one. There was also an initial GLEP attempt but it
never even reached the draft stage.

This GLEP aims to finally provide basic standardization for the use of
git in the Gentoo repository. It aims to focus purely on Gentoo-specific 
standards and not git usage in general. It doesn't mean to be a complete
guide but a formal basis on top of which official guides could be
created.

==Specification==
===Branching model===
The main branch of the Gentoo repository is the <kbd>master</kbd>
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.

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.

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.

Unless stated otherwise, the rules set by this specification apply to
the master branch only. The development branches can use relaxed rules.

Rewriting history (i.e. force pushes) of the master branch is forbidden.

===Merge commits===
The use of merge commits in the Gentoo repository is strongly
discouraged. Usually it is preferable to rebase instead. However, the
developers are allowed to use merge commits in justified cases. Merge
commits can be only used to merge additional branches, the use of
implicit <kbd>git pull</kbd> merges is entirely forbidden.

In a merge commit that is committed straight to the Gentoo repository,
the first parent is expected to reference an actual Gentoo commit
preceding the merge, while the remaining parents can be used to
reference external repositories. The commits following the first parent
are required to conform to this specification alike regular Gentoo
commits. The additional commits following other parents can use relaxed
rules.

===OpenPGP signatures===
Each commit in the Gentoo repository must be signed using the
committer's OpenPGP key. Furthermore, each push to the repository must
be signed using the key belonging to the developer performing the push
(matched via the SSH key).

The requirements for OpenPGP keys are covered by [[GLEP:63|GLEP 63]].

===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.

It is technically impossible to always respect all of the three rules,
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
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.

===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 (<kbd>git log --
oneline</kbd>, 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
<kbd>#nnnnnn</kbd> or likewise. The summary line must not exceed 69
characters, and must not be wrapped.

The suggested logical unit name formats are:
* for a package, <kbd>category/package: …</kbd>;
* for an eclass, <kbd>name.eclass: …</kbd>;
* for other directories or files, their path or filename (as long as a
developer reading the commit messages is able to figure out what it is)
— e.g. <kbd>licenses/foo: …</kbd>, <kbd>package.mask: …</kbd>.

The body is included in the full commit log (<kbd>git log</kbd>,
detailed commit info on gitweb/GitHub, mail body). It is optional, and
it can be used to describe the commit in more detail if the summary line
is not sufficient. It is generally a good idea to repeat the information
contained in the summary (except for the logical unit) since the summary
is frequently formatted as a title. The body should be wrapped at 72
characters. It can contain multiple paragraphs, separated by empty
lines.

The tag part is included in the full commit log as an extension to the
body. It consists of one or more lines consisting of key, followed by a
colon and a space, followed by value. Git does not enforce any
standardization of the keys, and the tag format is ''not'' meant for
machine processing.

A few tags of common use are:
* user-related tags:
** <kbd>Acked-by: Full Name <email@example.com></kbd> — commit approved
by another person (usually without detailed review),
** <kbd>Reported-by: Full Name <email@example.com></kbd>,
** <kbd>Reviewed-by: Full Name <email@example.com></kbd> — usually
indicates full review,
** <kbd>Signed-off-by: Full Name <email@example.com></kbd> — DCO
approval (not used in Gentoo right now),
** <kbd>Suggested-by: Full Name <email@example.com></kbd>, 
** <kbd>Tested-by: Full Name <email@example.com></kbd>.
* commit-related tags:
** <kbd>Fixes: commit-id (commit message)</kbd> — to indicate fixing a
previous commit,
** <kbd>Reverts: commit-id (commit message)</kbd> — to indicate
reverting a previous commit,
* bug tracker-related tags:
** <kbd>Bug: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>; — to
reference a bug,
** <kbd>Closes: <nowiki>https://github.com/gentoo/gentoo/pull/NNNN</nowi
ki></kbd>; — to automatically close a GitHub pull request,
** <kbd>Fixes: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>; —
to indicate a fixed bug,
* package manager tags:
** <kbd>Package-Manager: …</kbd> — used by repoman to indicate Portage
version,
** <kbd>RepoMan-Options: …</kbd> — used by repoman to indicate repoman
options.

The bug tracker-related tags can be used to extend the body message.
However, they should be skipped if the bug number is already provided in
the summary and there is no explicit body.

==Rationale==
===Branching model===
The model of multiple developers pushing concurrently to the repository
containing all packages is preserved from CVS. The developers have
discussed the possibility of using other models, in particular of using
multiple branches for developers that are afterwards automatically
merged into the master branch. However, it was determined that there is
no need to use a more complex model at the moment and the potential
problems with them outweighed the benefits.

The necessity of rebasing is a natural consequence of concurrent work,
along with the ban of reverse merge commits. Since rebasing a number of
commits can take a few seconds or even more, another developer sometimes
commits during that time, enforcing another rebase.

In the past, there were cases of developers using automated scripts
which created single commits, ran repoman and pushed them straight to
the repository. This resulted in pushes from a single developer every
10-15 seconds which made it impossible for other developers to rebase
larger commit batches. This kind of workflow is therefore strongly
discouraged.

Creating multiple short-time branches is discouraged as it implies
additional transfer for users cloning the repository and additional
maintenance burden. Since the git migration, the developers have created
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. Keeping branches local or hosting them outside Gentoo Infra
(e.g. on GitHub) reduces the burden on our users, even if the developers
do not clean after themselves.

===Merge commits===
Merge commits have been debated multiple times in various media, in
particular IRC. They have very verbose opponents whose main argument is
that they make history unreadable. At the same time, it has been
frequently pointed out that merge commits have valid use cases. To
satisfy both groups, this specification strongly discourages merge
commits but allows their use in justified cases.

Most importantly, the implicit merge commits created by <kbd>git
pull</kbd> are forbbiden. Those merges have no real value or justified
use case, and since they are created implicitly by default there have
been historical cases where developers pushed them unintentionally. They
are banned explicitly to emphasize the necessity of adjusting git
configuration to the developers.

When processing merge commits, it is important to explicitly distinguish
the parent that represents 'real' Gentoo history from the one(s) that
represent external branches. The former can either be an existing Gentoo
commit or a commit that the developer has prepared (on top of existing
Gentoo history) before merging the branch. For this reason, it is
important to enforce the full set of Gentoo policies on this parent and
the commits preceding it. On the other hand, the external branches can
be treated similarly to development branches. Relaxing the rules for
external branches also makes it possible to merge user contributions
with original user OpenPGP signatures, while adding a final developer
signature on top of the merge commit.

When using <kbd>git merge ''foo''</kbd>, the first parent represents the
current <kbd>HEAD</kbd> and the second one the merged branch. This is
the model used by the specification.

===OpenPGP signatures===
The signature requirements strictly correspond to the git setup deployed
by the Infrastructure team.

The commit signatures provide an ability to verify the authenticity of
all commits throughout the Gentoo repository history (to the point of
git conversion). The push signatures mostly serve the purpose of
additional authentication for the developer pushing a specific set of
commits.

===Splitting commits===
The goal of the commit splitting rules is to make the best use of git
while avoiding enforcing too much overhead on the developer and
optimizing to avoid interim broken commits.

Splitting commits by logical changes improves the readability and makes
it easier to revert a specific change while preserving the remaining
(irrelevant) changes. The changes done by a developer are easier to
comprehend when the reviewer can follow them in the specific order done
by the author, rather than combined with other changes.

Splitting commits on logical unit boundary was used since CVS times.
Mostly it improves readability via making it possible to include the
unit (package, eclass…) name in the commit message — so that developers
perceive what specific packages are affected by the change without
having to look into diffstat.

Requiring commits to be non-'broken' is meant to preserve a good quality
git history of the repository. This means that the users can checkout an
interim commit without risking a major problem such as a missing
dependency that is being added by the commit following it. It also makes
it safer to revert the most recent changes with reduced risk of exposing
a breakage.

Those rules partially overlap, and if that is the case, the developers
are expected to use common sense to determine the course of action that
gives the best result. Furthermore, requiring the strict following of
the rules would mean a lot of additional work for developers and a lot
of additional commits for no real benefit.

The examples are provided to make it possible for the developers to get
a 'feeling' how to work with the rules.

===Commit messages===
The basic commit message format is similar to the one used by other
projects, and provides for reasonably predictable display of results.

The summary line is meant to provide a good concise summary of the
changes. It is included in the short logs, and should include all the
information to help developer determine whether he is interested in
looking into the commit details. Including the logical unit name
accounts for the fact that most of the Gentoo commits are specific to
those units (e.g. packages). The length limit is meant to avoid wrapping
the shortlog — which could result in unreadable <kbd>git log --
oneline</kbd> or ugly mid-word ellipsis on GitHub.

The body is meant to provide the detailed information for a commit. It
is usually displayed verbatim, and the use of paragraphs along with line
wrapping is meant to improve readability. The body should include the
information contained in the summary since the two are sometimes really
disjoint, and expecting the user to read body as a continuation of
summary is confusing. For example, in <kbd>git send-email</kbd>, the
summary line is used to construct the mail's summary and is therefore
disjoint from the body.

The tag section is a traditional way of expressing quasi-machine-
readable data. However, the commit messages are not really suited for
machine use and only a few tags are actually processed by scripts. The
specification tries to provide a concise set of potentially useful tags
collected from various projects (the Linux kernel, X.org). Those tags
can be used interchangeably with plaintext explanation in the body.

The only tag defined by git itself is the <kbd>Signed-off-by</kbd> line,
that is created by <kbd>git commit -s</kbd>. However, Gentoo does not
currently enforce a DCO consistently, and therefore it is meaningless.

The only tag subject to machine processing is the <kbd>Closes</kbd> line
that is used by GitHub to automatically close pull requests (and issues
— however, Gentoo does not use GitHub's issue tracker).

All the remaining tags serve purely as a user convenience.

Historically, Gentoo has been using a few tags starting with <kbd>X-
</kbd>. 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.

Gentoo developers are still frequently using <kbd>Gentoo-Bug</kbd> tag,
sometimes followed by <kbd>Gentoo-Bug-URL</kbd>. Using both
simultaneously is meaningless (they are redundant), and using the former
has no advantages over using the classic <kbd>#nnnnnn</kbd> form in the
summary or the body.

==Backwards Compatibility==
Most of the new policy will apply to the commits following its approval.
Backwards compatibility is not relevant there.

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.

==Reference implementation==
All of the elements requiring explicit implementation on the git
infrastructure are implemented already. In particular this includes:
* blocking force pushes on the <kbd>master</kbd> branch,
* requiring signed commits on the <kbd>master</kbd> branch,
* requiring signed pushes to the repository.

The remaining elements are either non-obligatory or non-enforceable at
infrastructure level.

RepoMan suggests starting the commit message with package name since
commit [https://gitweb.gentoo.org/proj/portage.git/commit/?id=46dafadff5
8da0220511f20480b73ad09f913430
46dafadff58da0220511f20480b73ad09f913430].

==Acknowledgements==
Most of the foundations for this specification were laid out by
[[User:Hasufell|Julian Ospald (hasufell)]] in his initial version of
[[Gentoo git workflow]] article.

==Copyright==

This work is licensed under the Creative Commons Attribution-ShareAlike
3.0 Unported License. To view a copy of this license, visit http://creat
ivecommons.org/licenses/by-sa/3.0/.

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Nicolas Bock]

[-- Attachment #1: Type: text/plain, Size: 826 bytes --]

On Tue, Jul 25, 2017 at 10:05:06AM +0200, 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
>
>The basic idea is that the GLEP provides basic guidelines for using git,
>and then we write a proper manual on top of it (right now, all the pages
>about it end up as a mix of requirements and a partial git manual).
>
>What do you think about it? Is there anything else that needs being
>covered?

I like it. +1

>Copy of the markup for inline comments follows.


-- 
Nicolas Bock <nicolasbock@gentoo.org>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 981 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Dirkjan Ochtman]

[-- Attachment #1: Type: text/plain, Size: 234 bytes --]

On Tue, Jul 25, 2017 at 10:05 AM, Michał Górny <mgorny@gentoo.org> wrote:

> What do you think about it? Is there anything else that needs being
> covered?
>

Looks good to me. Thanks for writing it up!

Cheers,

Dirkjan

[-- Attachment #2: Type: text/html, Size: 585 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Tobias Klausmann]

Hi! 

On Tue, 25 Jul 2017, Michał Górny wrote:
> The summary line is included in the short logs (<kbd>git log --
> oneline</kbd>, 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
> <kbd>#nnnnnn</kbd> or likewise. The summary line must not exceed 69
> characters, and must not be wrapped.

This limit can be a problem if there's a nontrivial change to the
more than 80 packages in the tree that have more than forty characters in
cat/pkg[0]. Is the only option there to do word-smithing or
making the commit summary less usefu?

Or do we have a "violate if necessary" agreement regarding that?


Regards,
Tobias

[0] 
$ cd /usr/portage
$ ls -d *-*/*|awk '{if (length>=40) {print length, $0}}'|sort -n


-- 
Sent from aboard the Culture ship
	GSV Of Course I Still Love You

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michael Orlitzky]

On 07/25/2017 04:05 AM, Michał Górny wrote:
> 
> Here's the current draft:
> https://wiki.gentoo.org/wiki/User:MGorny/GLEP:Git
> 

It's mostly fine, but there are two changes I disagree with:

> 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.

We shouldn't play games in the repo and hope that everything works out
if we wait to push until just the right time. We're not going to run out
of numbers -- it's simpler and more correct to do a new revision with
each commit.


> 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 #nnnnnn form in the summary or the
> body.

There are two main advantages over having the bug number in the summary.
Space is at a premium in the summary, as Tobias pointed out, and the

  Gentoo-Bug: whatever

format is trivially machine-readable, whereas sticking it somewhere else
is less so.

And just a reminder -- Gokturk worked to get a lot of this stuff into
the devmanual, e.g.

  https://devmanual.gentoo.org/ebuild-maintenance/index.html

Some of that is important, like the warning not to use "bug #x" in the
body of the commit message.

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michał Górny]

Dnia 25 lipca 2017 12:59:21 CEST, Tobias Klausmann <klausman@gentoo.org> napisał(a):
>Hi! 
>
>On Tue, 25 Jul 2017, Michał Górny wrote:
>> The summary line is included in the short logs (<kbd>git log --
>> oneline</kbd>, 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
>> <kbd>#nnnnnn</kbd> or likewise. The summary line must not exceed 69
>> characters, and must not be wrapped.
>
>This limit can be a problem if there's a nontrivial change to the
>more than 80 packages in the tree that have more than forty characters
>in
>cat/pkg[0]. Is the only option there to do word-smithing or
>making the commit summary less usefu?
>
>Or do we have a "violate if necessary" agreement regarding that?

Yeah, i meant to apply the "must not" to wrapping but "should not" to length. Though I suggest you to ellipsize the package name, if it is unambiguous enough.

The problem is that if you exceed the length, the summary will be usually cut one way or another anyway.

>
>
>Regards,
>Tobias
>
>[0] 
>$ cd /usr/portage
>$ ls -d *-*/*|awk '{if (length>=40) {print length, $0}}'|sort -n


-- 
Best regards,
Michał Górny (by phone)

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Jonas Stein]

Hi everyone,

> Here's the current draft:
> https://wiki.gentoo.org/wiki/User:MGorny/GLEP:Git
> 
> The basic idea is that the GLEP provides basic guidelines for using git,
> and then we write a proper manual on top of it (right now, all the pages
> about it end up as a mix of requirements and a partial git manual).
> 
> What do you think about it? Is there anything else that needs being
> covered?

Thank you, Michał, for preparing an official guide from all the spread
informations. I think it is important for Gentoo to have such GLEP.

I think we should not bundle GLEPs to companies, but keep it more
abstract. The GLEP should still be valid, if we do not use github
anymore. Many large repositories have shut down in the last years. Even
after years we have not fixed all ebuilds [1]. We must be prepared, to
loose github very suddenly and should not hope that it will end with an
announcement years before.


Hence, I suggest to write the GLEP without naming "github" a single time.

[1] https://wiki.gentoo.org/wiki/Upstream_repository_shutdowns

-- 
Best,
Jonas

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michał Górny]

Dnia 25 lipca 2017 13:25:38 CEST, Michael Orlitzky <mjo@gentoo.org> napisał(a):
>On 07/25/2017 04:05 AM, Michał Górny wrote:
>> 
>> Here's the current draft:
>> https://wiki.gentoo.org/wiki/User:MGorny/GLEP:Git
>> 
>
>It's mostly fine, but there are two changes I disagree with:
>
>> 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.
>
>We shouldn't play games in the repo and hope that everything works out
>if we wait to push until just the right time. We're not going to run
>out
>of numbers -- it's simpler and more correct to do a new revision with
>each commit.

I have no clue what you mean. I'm just saying that if you push 10 changes in 10 commits, you don't have to go straight to -r10 in a single push.

>
>
>> 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 #nnnnnn form in the summary or the
>> body.
>
>There are two main advantages over having the bug number in the
>summary.
>Space is at a premium in the summary, as Tobias pointed out, and the
>
>  Gentoo-Bug: whatever
>
>format is trivially machine-readable, whereas sticking it somewhere
>else
>is less so.

Except that there is no machines using it. In all contexts, using full URL for machine readability is better as it works with all software out of the box.

>
>And just a reminder -- Gokturk worked to get a lot of this stuff into
>the devmanual, e.g.
>
>  https://devmanual.gentoo.org/ebuild-maintenance/index.html
>
>Some of that is important, like the warning not to use "bug #x" in the
>body of the commit message.


-- 
Best regards,
Michał Górny (by phone)

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michael Orlitzky]

On 07/25/2017 07:52 AM, Michał Górny wrote:
> 
> I have no clue what you mean. I'm just saying that if you push 10
> changes in 10 commits, you don't have to go straight to -r10 in a
> single push.
> 

Exactly. Do that instead of hoping that no one checks out your
intermediate commits. There's no limit to the number of revisions we can
have, and trying to keep track of when it's safe to push in your head is
asking for trouble.

[gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow

[Michael Palimaka]

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 (<kbd>git log --
> oneline</kbd>, 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
> <kbd>#nnnnnn</kbd> 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.

> ** <kbd>Bug: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>; — to
> reference a bug,
> ** <kbd>Closes: <nowiki>https://github.com/gentoo/gentoo/pull/NNNN</nowi
> ki></kbd>; — to automatically close a GitHub pull request,
> ** <kbd>Fixes: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>; —
> 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 <kbd>Gentoo-Bug</kbd> tag,
> sometimes followed by <kbd>Gentoo-Bug-URL</kbd>. Using both
> simultaneously is meaningless (they are redundant), and using the former
> has no advantages over using the classic <kbd>#nnnnnn</kbd> 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?

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Joshua Kinard]

On 07/25/2017 04:05, 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
> 
> The basic idea is that the GLEP provides basic guidelines for using git,
> and then we write a proper manual on top of it (right now, all the pages
> about it end up as a mix of requirements and a partial git manual).
> 
> What do you think about it? Is there anything else that needs being
> covered?
> 
> Copy of the markup for inline comments follows.

I haven't seen it mentioned yet, but will this GLEP update or replace this
existing Wiki article on using git w/ Gentoo?:

https://wiki.gentoo.org/wiki/Gentoo_git_workflow

Some of the step-by-step bits in the above Wiki page look like good candidates
to be integrated into the GLEP.  It also contains guidelines on writing commit
messages, such as limiting the first line to ~50 characters, an optional body
wrapped at 75 chars/line, and including the usual git tags for sign-off and
such.  Though, I like the explicitness of the GLEP's text on a few things more.

-- 
Joshua Kinard
Gentoo/MIPS
kumba@gentoo.org
6144R/F5C6C943 2015-04-27
177C 1972 1FB8 F254 BAD0 3E72 5C63 F4E3 F5C6 C943

"The past tempts us, the present confuses us, the future frightens us.  And our
lives slip away, moment by moment, lost in that vast, terrible in-between."

--Emperor Turhan, Centauri Republic

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 860 bytes --]

On wto, 2017-07-25 at 08:26 -0400, Michael Orlitzky wrote:
> On 07/25/2017 07:52 AM, Michał Górny wrote:
> > 
> > I have no clue what you mean. I'm just saying that if you push 10
> > changes in 10 commits, you don't have to go straight to -r10 in a
> > single push.
> > 
> 
> Exactly. Do that instead of hoping that no one checks out your
> intermediate commits. There's no limit to the number of revisions we can
> have, and trying to keep track of when it's safe to push in your head is
> asking for trouble.
> 

How is that relevant? Revision bumps are merely a tool to encourage
'automatic' rebuilds of packages during @world upgrade. I can't think of
a single use case where somebody would actually think it sane to
checkout one commit after another, and run @world upgrade in the middle
of it.

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Rich Freeman]

On Tue, Jul 25, 2017 at 7:52 AM, Michał Górny <mgorny@gentoo.org> wrote:
>
> Except that there is no machines using it. In all contexts, using full URL for machine readability is better as it works with all software out of the box.
>

Until the domain name of the bugzilla server changes/etc.  Even if we
migrated all the old bugs the URLs would break.  That might be an
argument for not having a full URL.

There would also be less variation.  Bug: 123456 is pretty unambiguous
as a reference.  When you start having http vs https and maybe a few
different ways of creating a URL to a bug it could get messier.

That said, I really don't have a strong opinion on this.

-- 
Rich

Re: [gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 4279 bytes --]

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 (<kbd>git log --
> > oneline</kbd>, 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
> > <kbd>#nnnnnn</kbd> 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.

> > ** <kbd>Bug: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>;; — to
> > reference a bug,
> > ** <kbd>Closes: <nowiki>https://github.com/gentoo/gentoo/pull/NNNN</nowi
> > ki></kbd>; — to automatically close a GitHub pull request,
> > ** <kbd>Fixes: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>;; —
> > 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 <kbd>Gentoo-Bug</kbd> tag,
> > sometimes followed by <kbd>Gentoo-Bug-URL</kbd>. Using both
> > simultaneously is meaningless (they are redundant), and using the former
> > has no advantages over using the classic <kbd>#nnnnnn</kbd> 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

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 1848 bytes --]

On wto, 2017-07-25 at 08:54 -0400, Joshua Kinard wrote:
> On 07/25/2017 04:05, 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
> > 
> > The basic idea is that the GLEP provides basic guidelines for using git,
> > and then we write a proper manual on top of it (right now, all the pages
> > about it end up as a mix of requirements and a partial git manual).
> > 
> > What do you think about it? Is there anything else that needs being
> > covered?
> > 
> > Copy of the markup for inline comments follows.
> 
> I haven't seen it mentioned yet, but will this GLEP update or replace this
> existing Wiki article on using git w/ Gentoo?:
> 
> https://wiki.gentoo.org/wiki/Gentoo_git_workflow

We will probably remove it in favor of a proper devmanual section.
Proxy-maint already stopped using it because there's too much noise
there.

> Some of the step-by-step bits in the above Wiki page look like good candidates
> to be integrated into the GLEP.

Could you be more specific?

>   It also contains guidelines on writing commit
> messages, such as limiting the first line to ~50 characters, an optional body
> wrapped at 75 chars/line, and including the usual git tags for sign-off and
> such.  Though, I like the explicitness of the GLEP's text on a few things more.

There is a large section on commit messages in the GLEP. Though it uses
69 as the technical limit of summary line, since ~50 is realistically
hard to achieve for Gentoo.

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 1203 bytes --]

On wto, 2017-07-25 at 09:26 -0400, Rich Freeman wrote:
> On Tue, Jul 25, 2017 at 7:52 AM, Michał Górny <mgorny@gentoo.org> wrote:
> > 
> > Except that there is no machines using it. In all contexts, using full URL for machine readability is better as it works with all software out of the box.
> > 
> 
> Until the domain name of the bugzilla server changes/etc.  Even if we
> migrated all the old bugs the URLs would break.  That might be an
> argument for not having a full URL.

This is a very stupid argument. If we ever break bug URLs, commit
messages are the *least* of our concerns.

> There would also be less variation.  Bug: 123456 is pretty unambiguous
> as a reference.  When you start having http vs https and maybe a few
> different ways of creating a URL to a bug it could get messier.

Except that 123456 could refer to any bugtracker anywhere. No reasonable
tool will do anything with that number since it's ambiguous by
definition.

And if I were to use stupid arguments, then I should point out if we
ever have a review platform, then the numbers would suddenly become
ambiguous -- is it Bugzilla or the review platform?

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michael Orlitzky]

On 07/25/2017 09:23 AM, Michał Górny wrote:
> 
> How is that relevant? Revision bumps are merely a tool to encourage
> 'automatic' rebuilds of packages during @world upgrade. I can't think of
> a single use case where somebody would actually think it sane to
> checkout one commit after another, and run @world upgrade in the middle
> of it.
> 

Revisions are to indicate that one incarnation of a package differs from
another in a way that the user or package manager might care about. And
on principal, it's no business of yours what people want to do with
their tree. If someone wants to check out successive commits and emerge
@world, he's within his rights to do so.

This is relevant because your proposed policy,

  * presumes to know how people will use the tree, and places arbitrary
    restrictions on them

  * can cause problems if those assumptions don't hold

  * requires developers to think about when it's safe to push (Did I
    push those changes last night? Do I need another revision?)

  * and is more complicated than the safe solution, anyway

Here's my proposal regarding revisions:

  If you make a commit that requires a revision, make a revision.

If you wind up with an -r15 in the tree, who cares? It's simpler, safer,
and less to think about.

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Mike Gilbert]

On Tue, Jul 25, 2017 at 12:12 PM, Michael Orlitzky <mjo@gentoo.org> wrote:
> On 07/25/2017 09:23 AM, Michał Górny wrote:
>>
>> How is that relevant? Revision bumps are merely a tool to encourage
>> 'automatic' rebuilds of packages during @world upgrade. I can't think of
>> a single use case where somebody would actually think it sane to
>> checkout one commit after another, and run @world upgrade in the middle
>> of it.
>>
>
> Revisions are to indicate that one incarnation of a package differs from
> another in a way that the user or package manager might care about. And
> on principal, it's no business of yours what people want to do with
> their tree. If someone wants to check out successive commits and emerge
> @world, he's within his rights to do so.

I don't feel I should be obligated by policy to support this use case.
One revbump per push seems sufficiently safe for 99.9% of users.

If you want to do more revbumps, you are free to do so.

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michael Orlitzky]

On 07/25/2017 04:29 PM, Mike Gilbert wrote:
> 
> I don't feel I should be obligated by policy to support this use case.
> One revbump per push seems sufficiently safe for 99.9% of users.
> 
> If you want to do more revbumps, you are free to do so.
> 

Can I also delete packages and break the tree so long as I put
everything back before I push?

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 647 bytes --]

On wto, 2017-07-25 at 16:31 -0400, Michael Orlitzky wrote:
> On 07/25/2017 04:29 PM, Mike Gilbert wrote:
> > 
> > I don't feel I should be obligated by policy to support this use case.
> > One revbump per push seems sufficiently safe for 99.9% of users.
> > 
> > If you want to do more revbumps, you are free to do so.
> > 
> 
> Can I also delete packages and break the tree so long as I put
> everything back before I push?

That is not the same, and you know that. Plus, there's a major
difference between not doing unnecessary work and purposely doing
something awful just to prove a point.

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Rich Freeman]

On Tue, Jul 25, 2017 at 4:29 PM, Mike Gilbert <floppym@gentoo.org> wrote:
> On Tue, Jul 25, 2017 at 12:12 PM, Michael Orlitzky <mjo@gentoo.org> wrote:
>> On 07/25/2017 09:23 AM, Michał Górny wrote:
>>>
>>> How is that relevant? Revision bumps are merely a tool to encourage
>>> 'automatic' rebuilds of packages during @world upgrade. I can't think of
>>> a single use case where somebody would actually think it sane to
>>> checkout one commit after another, and run @world upgrade in the middle
>>> of it.
>>>
>>
>> Revisions are to indicate that one incarnation of a package differs from
>> another in a way that the user or package manager might care about. And
>> on principal, it's no business of yours what people want to do with
>> their tree. If someone wants to check out successive commits and emerge
>> @world, he's within his rights to do so.
>
> I don't feel I should be obligated by policy to support this use case.
> One revbump per push seems sufficiently safe for 99.9% of users.
>
> If you want to do more revbumps, you are free to do so.
>

What is the point of separating changes by commits if we don't
generally try to keep each commit working?

Sure, there are some cases where it is just going to be too painful to
ensure that, and so it doesn't have to be an absolute rule.

However, if somebody is checking out a tree at some point in the past
they shouldn't have to try to figure out where the last push boundary
was to ensure that it is sane.  Use cases for that include updating
older systems progressively, or bisecting a problem.

-- 
Rich

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 1948 bytes --]

On wto, 2017-07-25 at 18:26 -0400, Rich Freeman wrote:
> On Tue, Jul 25, 2017 at 4:29 PM, Mike Gilbert <floppym@gentoo.org> wrote:
> > On Tue, Jul 25, 2017 at 12:12 PM, Michael Orlitzky <mjo@gentoo.org> wrote:
> > > On 07/25/2017 09:23 AM, Michał Górny wrote:
> > > > 
> > > > How is that relevant? Revision bumps are merely a tool to encourage
> > > > 'automatic' rebuilds of packages during @world upgrade. I can't think of
> > > > a single use case where somebody would actually think it sane to
> > > > checkout one commit after another, and run @world upgrade in the middle
> > > > of it.
> > > > 
> > > 
> > > Revisions are to indicate that one incarnation of a package differs from
> > > another in a way that the user or package manager might care about. And
> > > on principal, it's no business of yours what people want to do with
> > > their tree. If someone wants to check out successive commits and emerge
> > > @world, he's within his rights to do so.
> > 
> > I don't feel I should be obligated by policy to support this use case.
> > One revbump per push seems sufficiently safe for 99.9% of users.
> > 
> > If you want to do more revbumps, you are free to do so.
> > 
> 
> What is the point of separating changes by commits if we don't
> generally try to keep each commit working?
> 
> Sure, there are some cases where it is just going to be too painful to
> ensure that, and so it doesn't have to be an absolute rule.
> 
> However, if somebody is checking out a tree at some point in the past
> they shouldn't have to try to figure out where the last push boundary
> was to ensure that it is sane.  Use cases for that include updating
> older systems progressively, or bisecting a problem.

Guys, please cut this FUD.

Nothing is broken if you don't revbump. The only thing that doesn't
happen is that the PM isn't obliged to suggest user to upgrade.

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Rich Freeman]

On Tue, Jul 25, 2017 at 6:30 PM, Michał Górny <mgorny@gentoo.org> wrote:
> On wto, 2017-07-25 at 18:26 -0400, Rich Freeman wrote:
>> On Tue, Jul 25, 2017 at 4:29 PM, Mike Gilbert <floppym@gentoo.org> wrote:
>> > On Tue, Jul 25, 2017 at 12:12 PM, Michael Orlitzky <mjo@gentoo.org> wrote:
>> > > On 07/25/2017 09:23 AM, Michał Górny wrote:
>> > > >
>> > > > How is that relevant? Revision bumps are merely a tool to encourage
>> > > > 'automatic' rebuilds of packages during @world upgrade. I can't think of
>> > > > a single use case where somebody would actually think it sane to
>> > > > checkout one commit after another, and run @world upgrade in the middle
>> > > > of it.
>> > > >
>> > >
>> > > Revisions are to indicate that one incarnation of a package differs from
>> > > another in a way that the user or package manager might care about. And
>> > > on principal, it's no business of yours what people want to do with
>> > > their tree. If someone wants to check out successive commits and emerge
>> > > @world, he's within his rights to do so.
>> >
>> > I don't feel I should be obligated by policy to support this use case.
>> > One revbump per push seems sufficiently safe for 99.9% of users.
>> >
>> > If you want to do more revbumps, you are free to do so.
>> >
>>
>> What is the point of separating changes by commits if we don't
>> generally try to keep each commit working?
>>
>> Sure, there are some cases where it is just going to be too painful to
>> ensure that, and so it doesn't have to be an absolute rule.
>>
>> However, if somebody is checking out a tree at some point in the past
>> they shouldn't have to try to figure out where the last push boundary
>> was to ensure that it is sane.  Use cases for that include updating
>> older systems progressively, or bisecting a problem.
>
> Guys, please cut this FUD.
>
> Nothing is broken if you don't revbump. The only thing that doesn't
> happen is that the PM isn't obliged to suggest user to upgrade.
>

I wasn't referring to revbumps.  Just to ensuring that all commits
generally work even if they aren't pushed.

-- 
Rich

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 2442 bytes --]

On wto, 2017-07-25 at 18:46 -0400, Rich Freeman wrote:
> On Tue, Jul 25, 2017 at 6:30 PM, Michał Górny <mgorny@gentoo.org> wrote:
> > On wto, 2017-07-25 at 18:26 -0400, Rich Freeman wrote:
> > > On Tue, Jul 25, 2017 at 4:29 PM, Mike Gilbert <floppym@gentoo.org> wrote:
> > > > On Tue, Jul 25, 2017 at 12:12 PM, Michael Orlitzky <mjo@gentoo.org> wrote:
> > > > > On 07/25/2017 09:23 AM, Michał Górny wrote:
> > > > > > 
> > > > > > How is that relevant? Revision bumps are merely a tool to encourage
> > > > > > 'automatic' rebuilds of packages during @world upgrade. I can't think of
> > > > > > a single use case where somebody would actually think it sane to
> > > > > > checkout one commit after another, and run @world upgrade in the middle
> > > > > > of it.
> > > > > > 
> > > > > 
> > > > > Revisions are to indicate that one incarnation of a package differs from
> > > > > another in a way that the user or package manager might care about. And
> > > > > on principal, it's no business of yours what people want to do with
> > > > > their tree. If someone wants to check out successive commits and emerge
> > > > > @world, he's within his rights to do so.
> > > > 
> > > > I don't feel I should be obligated by policy to support this use case.
> > > > One revbump per push seems sufficiently safe for 99.9% of users.
> > > > 
> > > > If you want to do more revbumps, you are free to do so.
> > > > 
> > > 
> > > What is the point of separating changes by commits if we don't
> > > generally try to keep each commit working?
> > > 
> > > Sure, there are some cases where it is just going to be too painful to
> > > ensure that, and so it doesn't have to be an absolute rule.
> > > 
> > > However, if somebody is checking out a tree at some point in the past
> > > they shouldn't have to try to figure out where the last push boundary
> > > was to ensure that it is sane.  Use cases for that include updating
> > > older systems progressively, or bisecting a problem.
> > 
> > Guys, please cut this FUD.
> > 
> > Nothing is broken if you don't revbump. The only thing that doesn't
> > happen is that the PM isn't obliged to suggest user to upgrade.
> > 
> 
> I wasn't referring to revbumps.  Just to ensuring that all commits
> generally work even if they aren't pushed.
> 

In that case, it is explicitly listed as the third rule for splitting.

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 668 bytes --]

>>>>> On Tue, 25 Jul 2017, Michał Górny wrote:

> On wto, 2017-07-25 at 09:26 -0400, Rich Freeman wrote:
>> There would also be less variation. Bug: 123456 is pretty
>> unambiguous as a reference. When you start having http vs https and
>> maybe a few different ways of creating a URL to a bug it could get
>> messier.

> Except that 123456 could refer to any bugtracker anywhere. No
> reasonable tool will do anything with that number since it's
> ambiguous by definition.

The same applies to #123456 in the summary line, though. I don't see a
good reason for using a URL after the "Bug:" keyword as long as bare
numbers are used elsewhere.

Ulrich

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Brian Evans]

[-- Attachment #1.1: Type: text/plain, Size: 3481 bytes --]

On 7/25/2017 4:05 AM, 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
> 
> The basic idea is that the GLEP provides basic guidelines for using git,
> and then we write a proper manual on top of it (right now, all the pages
> about it end up as a mix of requirements and a partial git manual).
> 
> What do you think about it? Is there anything else that needs being
> covered?
> 
> Copy of the markup for inline comments follows.

[cut]
> ===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.
> 
[cut]
> The tag part is included in the full commit log as an extension to the
> body. It consists of one or more lines consisting of key, followed by a
> colon and a space, followed by value. Git does not enforce any
> standardization of the keys, and the tag format is ''not'' meant for
> machine processing.
> 
> A few tags of common use are:
> * user-related tags:
> ** <kbd>Acked-by: Full Name <email@example.com></kbd> — commit approved
> by another person (usually without detailed review),
> ** <kbd>Reported-by: Full Name <email@example.com></kbd>,
> ** <kbd>Reviewed-by: Full Name <email@example.com></kbd> — usually
> indicates full review,
> ** <kbd>Signed-off-by: Full Name <email@example.com></kbd> — DCO
> approval (not used in Gentoo right now),
> ** <kbd>Suggested-by: Full Name <email@example.com></kbd>, 
> ** <kbd>Tested-by: Full Name <email@example.com></kbd>.
> * commit-related tags:
> ** <kbd>Fixes: commit-id (commit message)</kbd> — to indicate fixing a
> previous commit,
> ** <kbd>Reverts: commit-id (commit message)</kbd> — to indicate
> reverting a previous commit,
> * bug tracker-related tags:
> ** <kbd>Bug: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>; — to
> reference a bug,
> ** <kbd>Closes: <nowiki>https://github.com/gentoo/gentoo/pull/NNNN</nowi
> ki></kbd>; — to automatically close a GitHub pull request,
> ** <kbd>Fixes: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>; —
> to indicate a fixed bug,
> * package manager tags:
> ** <kbd>Package-Manager: …</kbd> — used by repoman to indicate Portage
> version,
> ** <kbd>RepoMan-Options: …</kbd> — used by repoman to indicate repoman
> options.
> 
> The bug tracker-related tags can be used to extend the body message.
> However, they should be skipped if the bug number is already provided in
> the summary and there is no explicit body.
> 

My concern on these tags is that some evangelist will come along and
demand that they always be included with every commit since they exist
in a GLEP.  They add very little value, IMO, and I doubt they will ever
be parsed or ever read.

I would object less if the committing tool, i.e. repoman, would provide
easy switches for common cases for uniformity.  I foresee more work on
my part to remember such lines and would have to look up the "current
syntax" as it goes through debate many times over as it already has.
(Both in the past and in this thread again).

Brian


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 834 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Kristian Fiskerstrand]

[-- Attachment #1.1: Type: text/plain, Size: 975 bytes --]

On 07/25/2017 01:25 PM, Michael Orlitzky wrote:
> There are two main advantages over having the bug number in the summary.
> Space is at a premium in the summary, as Tobias pointed out, and the
> 
>   Gentoo-Bug: whatever
> 
> format is trivially machine-readable, whereas sticking it somewhere else
> is less so.

Indeed, I'm in favor of keeping bug information in this format, whereby
Bug: <URL> is fine as a generic reference it will mostly be for upstream
issues or other distributions, whereby Gentoo-Bug: #nnnnnn is explicit
reference to our own tracker. An issue to consider is definition of this
label in terms of whether it takes a single value or a list and how to
do wrapping.. I'd likely expect possibility for multiple occurrences for
it but allowing multiple bug numbers specified comma separated

-- 
Kristian Fiskerstrand
OpenPGP keyblock reachable at hkp://pool.sks-keyservers.net
fpr:94CB AFDD 3034 5109 5618 35AA 0B7F 8B60 E3ED FAE3


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Kristian Fiskerstrand]

[-- Attachment #1.1: Type: text/plain, Size: 573 bytes --]

On 07/26/2017 11:21 AM, Ulrich Mueller wrote:
> The same applies to #123456 in the summary line, though. I don't see a
> good reason for using a URL after the "Bug:" keyword as long as bare
> numbers are used elsewhere.

For Bug you'd often refer to upstream reports or other distros, so you
need it in a generic form which url provides, having a separate
Gentoo-Bug properly defined to ID only solves the ambiguity.

-- 
Kristian Fiskerstrand
OpenPGP keyblock reachable at hkp://pool.sks-keyservers.net
fpr:94CB AFDD 3034 5109 5618 35AA 0B7F 8B60 E3ED FAE3


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow

[Kristian Fiskerstrand]

[-- Attachment #1.1: Type: text/plain, Size: 530 bytes --]

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Kristian Fiskerstrand]

[-- Attachment #1.1: Type: text/plain, Size: 819 bytes --]

On 07/25/2017 10:05 AM, Michał Górny wrote:
> ** <kbd>Fixes: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>; —
> to indicate a fixed bug,

At this point fixes is overloading
> ** <kbd>Fixes: commit-id (commit message)</kbd> — to indicate fixing a
> previous commit

This use should be forbidden.

> ** <kbd>Bug: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>; — to
> reference a bug,

See other comments in thread wrt Gentoo-Bug.

> ** <kbd>Closes: <nowiki>https://github.com/gentoo/gentoo/pull/NNNN</nowi
> ki></kbd>; — to automatically close a GitHub pull request,

Is this a generic tag for any pull request of any platform?

-- 
Kristian Fiskerstrand
OpenPGP keyblock reachable at hkp://pool.sks-keyservers.net
fpr:94CB AFDD 3034 5109 5618 35AA 0B7F 8B60 E3ED FAE3


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Rich Freeman]

On Wed, Jul 26, 2017 at 1:04 PM, Kristian Fiskerstrand <k_f@gentoo.org> wrote:
> On 07/26/2017 11:21 AM, Ulrich Mueller wrote:
>> The same applies to #123456 in the summary line, though. I don't see a
>> good reason for using a URL after the "Bug:" keyword as long as bare
>> numbers are used elsewhere.
>
> For Bug you'd often refer to upstream reports or other distros, so you
> need it in a generic form which url provides, having a separate
> Gentoo-Bug properly defined to ID only solves the ambiguity.
>

I was thinking that it would make far more sense to use "Bug" for
Gentoo bugs, and use something like "Reference" or "Remote-Bug" for
non-Gentoo bugs.  99% of the time commits will reference a Gentoo bug.
If you wanted to reference others you'd probably have it linked in the
Gentoo bug anyway so duplicating it in the commit seems wasteful.

In any case, I think what matters is picking one format and then
sticking it in the repoman template so that people don't have to type
it.

Also, I suggest using either URLs or bug numbers, but not both.
Otherwise you end up having to copy the URL over, then copy the ID
only and paste it in the summary.  That is an extra step.

-- 
Rich

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Kristian Fiskerstrand]

[-- Attachment #1.1: Type: text/plain, Size: 500 bytes --]

On 07/26/2017 07:20 PM, Rich Freeman wrote:
> Also, I suggest using either URLs or bug numbers, but not both.
> Otherwise you end up having to copy the URL over, then copy the ID
> only and paste it in the summary.  That is an extra step.

I wouldn't have bug ID in summary at all unless it provides external
value, it should be self-describing

-- 
Kristian Fiskerstrand
OpenPGP keyblock reachable at hkp://pool.sks-keyservers.net
fpr:94CB AFDD 3034 5109 5618 35AA 0B7F 8B60 E3ED FAE3


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow

[Sam Jorna]

[-- Attachment #1: Type: text/plain, Size: 835 bytes --]

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

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 858 bytes --]

Re: [gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow

[Daniel Campbell]

[-- Attachment #1.1: Type: text/plain, Size: 1579 bytes --]

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.

<bikeshed>
"Bug: xxxxxx" 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.
</bikeshed>
-- 
Daniel Campbell - Gentoo Developer
OpenPGP Key: 0x1EA055D6 @ hkp://keys.gnupg.net
fpr: AE03 9064 AE00 053C 270C  1DE4 6F7A 9091 1EA0 55D6


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Kristian Fiskerstrand]

[-- Attachment #1.1: Type: text/plain, Size: 627 bytes --]

On 07/26/2017 07:20 PM, Rich Freeman wrote:
> I was thinking that it would make far more sense to use "Bug" for
> Gentoo bugs, and use something like "Reference" or "Remote-Bug" for
> non-Gentoo bugs.  99% of the time commits will reference a Gentoo bug.

I like the idea of Reference for URL specification . This can be used as
a general property for other relevant discussion points as well, and
indeed frees up Bug to be used for Gentoo with numeric identifiers only.

-- 
Kristian Fiskerstrand
OpenPGP keyblock reachable at hkp://pool.sks-keyservers.net
fpr:94CB AFDD 3034 5109 5618 35AA 0B7F 8B60 E3ED FAE3


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 697 bytes --]

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

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 1133 bytes --]

On śro, 2017-07-26 at 19:17 +0200, Kristian Fiskerstrand wrote:
> On 07/25/2017 10:05 AM, Michał Górny wrote:
> > ** <kbd>Fixes: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>;; —
> > to indicate a fixed bug,
> 
> At this point fixes is overloading
> > ** <kbd>Fixes: commit-id (commit message)</kbd> — to indicate fixing a
> > previous commit
> 
> This use should be forbidden.

...because? But sure, you don't like it, let's remove it. Not that
anyone will actually prefer the things from the GLEP over anything else.

> > ** <kbd>Bug: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>;; — to
> > reference a bug,
> 
> See other comments in thread wrt Gentoo-Bug.
> 
> > ** <kbd>Closes: <nowiki>https://github.com/gentoo/gentoo/pull/NNNN</nowi
> > ki></kbd>; — to automatically close a GitHub pull request,
> 
> Is this a generic tag for any pull request of any platform?

No. As I've told multiple times already, there are *no* generic tags. It
just happens to be used by some random platforms. Some others use e.g.
'Fixes' which you forbade.

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Kristian Fiskerstrand]

[-- Attachment #1.1: Type: text/plain, Size: 1736 bytes --]

On 07/27/2017 03:52 PM, Michał Górny wrote:
> On śro, 2017-07-26 at 19:17 +0200, Kristian Fiskerstrand wrote:
>> On 07/25/2017 10:05 AM, Michał Górny wrote:
>>> ** <kbd>Fixes: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>;; —
>>> to indicate a fixed bug,
>>
>> At this point fixes is overloading
>>> ** <kbd>Fixes: commit-id (commit message)</kbd> — to indicate fixing a
>>> previous commit
>>
>> This use should be forbidden.
> 
> ...because? But sure, you don't like it, let's remove it. Not that
> anyone will actually prefer the things from the GLEP over anything else.
> 

Because it overloads the tag for multiple meanings and as such should be
different tags, we already have a tag that specifies the bug (namely
Bug, presuming we use Reference: for URL specification of relevant
upstream information or other discussions)

>>> ** <kbd>Bug: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>;; — to
>>> reference a bug,
>>
>> See other comments in thread wrt Gentoo-Bug.
>>
>>> ** <kbd>Closes: <nowiki>https://github.com/gentoo/gentoo/pull/NNNN</nowi
>>> ki></kbd>; — to automatically close a GitHub pull request,
>>
>> Is this a generic tag for any pull request of any platform?
> 
> No. As I've told multiple times already, there are *no* generic tags. It
> just happens to be used by some random platforms. Some others use e.g.
> 'Fixes' which you forbade.
> 

Isn't that the point of having a GLEP to begin with? Trying to
standardize the use of e.g the tags so that it has a consistent meaning
and can be useful?

-- 
Kristian Fiskerstrand
OpenPGP keyblock reachable at hkp://pool.sks-keyservers.net
fpr:94CB AFDD 3034 5109 5618 35AA 0B7F 8B60 E3ED FAE3


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 2059 bytes --]

On czw, 2017-07-27 at 15:54 +0200, Kristian Fiskerstrand wrote:
> On 07/27/2017 03:52 PM, Michał Górny wrote:
> > On śro, 2017-07-26 at 19:17 +0200, Kristian Fiskerstrand wrote:
> > > On 07/25/2017 10:05 AM, Michał Górny wrote:
> > > > ** <kbd>Fixes: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>;;; —
> > > > to indicate a fixed bug,
> > > 
> > > At this point fixes is overloading
> > > > ** <kbd>Fixes: commit-id (commit message)</kbd> — to indicate fixing a
> > > > previous commit
> > > 
> > > This use should be forbidden.
> > 
> > ...because? But sure, you don't like it, let's remove it. Not that
> > anyone will actually prefer the things from the GLEP over anything else.
> > 
> 
> Because it overloads the tag for multiple meanings and as such should be
> different tags, we already have a tag that specifies the bug (namely
> Bug, presuming we use Reference: for URL specification of relevant
> upstream information or other discussions)
> 
> > > > ** <kbd>Bug: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>;;; — to
> > > > reference a bug,
> > > 
> > > See other comments in thread wrt Gentoo-Bug.
> > > 
> > > > ** <kbd>Closes: <nowiki>https://github.com/gentoo/gentoo/pull/NNNN</nowi
> > > > ki></kbd>; — to automatically close a GitHub pull request,
> > > 
> > > Is this a generic tag for any pull request of any platform?
> > 
> > No. As I've told multiple times already, there are *no* generic tags. It
> > just happens to be used by some random platforms. Some others use e.g.
> > 'Fixes' which you forbade.
> > 
> 
> Isn't that the point of having a GLEP to begin with? Trying to
> standardize the use of e.g the tags so that it has a consistent meaning
> and can be useful?
> 

Tags are mentioned merely for convenience, and as examples. If you want
to request GitHub support to add support for special Gentoo tags you've
just invented, be my guest. But don't bother forwarding their reply to
me because I know their answer.

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Kristian Fiskerstrand]

[-- Attachment #1.1: Type: text/plain, Size: 1371 bytes --]

On 07/27/2017 03:58 PM, Michał Górny wrote:
>>>>> ** <kbd>Closes: <nowiki>https://github.com/gentoo/gentoo/pull/NNNN</nowi
>>>>> ki></kbd>; — to automatically close a GitHub pull request,
>>>> Is this a generic tag for any pull request of any platform?
>>> No. As I've told multiple times already, there are *no* generic tags. It
>>> just happens to be used by some random platforms. Some others use e.g.
>>> 'Fixes' which you forbade.
>>>
>> Isn't that the point of having a GLEP to begin with? Trying to
>> standardize the use of e.g the tags so that it has a consistent meaning
>> and can be useful?
>>
> Tags are mentioned merely for convenience, and as examples. If you want
> to request GitHub support to add support for special Gentoo tags you've
> just invented, be my guest. But don't bother forwarding their reply to
> me because I know their answer.

Right, so github automatically closes pull requests when encountering
Closes, that doesn't indicate that Closes can't be used for other
platforms to do similar things, or closing things manually if provided
through other channels. The current wording indicates it is only for
Github use "to automatically close a GitHub pull request,"

-- 
Kristian Fiskerstrand
OpenPGP keyblock reachable at hkp://pool.sks-keyservers.net
fpr:94CB AFDD 3034 5109 5618 35AA 0B7F 8B60 E3ED FAE3


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 1565 bytes --]

On czw, 2017-07-27 at 16:08 +0200, Kristian Fiskerstrand wrote:
> On 07/27/2017 03:58 PM, Michał Górny wrote:
> > > > > > ** <kbd>Closes: <nowiki>https://github.com/gentoo/gentoo/pull/NNNN</nowi
> > > > > > ki></kbd>; — to automatically close a GitHub pull request,
> > > > > 
> > > > > Is this a generic tag for any pull request of any platform?
> > > > 
> > > > No. As I've told multiple times already, there are *no* generic tags. It
> > > > just happens to be used by some random platforms. Some others use e.g.
> > > > 'Fixes' which you forbade.
> > > > 
> > > 
> > > Isn't that the point of having a GLEP to begin with? Trying to
> > > standardize the use of e.g the tags so that it has a consistent meaning
> > > and can be useful?
> > > 
> > 
> > Tags are mentioned merely for convenience, and as examples. If you want
> > to request GitHub support to add support for special Gentoo tags you've
> > just invented, be my guest. But don't bother forwarding their reply to
> > me because I know their answer.
> 
> Right, so github automatically closes pull requests when encountering
> Closes, that doesn't indicate that Closes can't be used for other
> platforms to do similar things, or closing things manually if provided
> through other channels. The current wording indicates it is only for
> Github use "to automatically close a GitHub pull request,"

...which is the only purpose it's being used for right now, and I
seriously doubt there will be any other use in the near future.

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 988 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Kristian Fiskerstrand]

[-- Attachment #1.1: Type: text/plain, Size: 1016 bytes --]

On 07/27/2017 04:11 PM, Michał Górny wrote:
>> Right, so github automatically closes pull requests when encountering
>> Closes, that doesn't indicate that Closes can't be used for other
>> platforms to do similar things, or closing things manually if provided
>> through other channels. The current wording indicates it is only for
>> Github use "to automatically close a GitHub pull request,"
> ...which is the only purpose it's being used for right now, and I
> seriously doubt there will be any other use in the near future.

That doesn't mean we shouldn't prepare for it in our specification, why
shouldn't I be able to use it for closing a pull request provided
through bitbucket or a git request-pull from my private gitolite? There
is absolutely no reason to mention github in the GLEP versus making it a
generic tag for closing a pull request.

-- 
Kristian Fiskerstrand
OpenPGP keyblock reachable at hkp://pool.sks-keyservers.net
fpr:94CB AFDD 3034 5109 5618 35AA 0B7F 8B60 E3ED FAE3


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

[gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow

[Duncan]

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

[gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow

[Duncan]

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 <kbd>master</kbd>
> 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

[Duncan]

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

[Duncan]

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 <kbd>X-
> </kbd>. 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 <kbd>Gentoo-Bug</kbd> 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 <kbd>Gentoo-Bug-URL</kbd>. Using both
> simultaneously is meaningless (they are redundant), and using the former
> has no advantages over using the classic <kbd>#nnnnnn</kbd> 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

[Duncan]

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

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Andreas K. Huettel]

[-- Attachment #1: Type: text/plain, Size: 2481 bytes --]

Am Dienstag, 25. Juli 2017, 10:05:06 CEST schrieb Michał Górny:
> 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
> 
> The basic idea is that the GLEP provides basic guidelines for using git,
> and then we write a proper manual on top of it (right now, all the pages
> about it end up as a mix of requirements and a partial git manual).
> 
> What do you think about it? Is there anything else that needs being
> covered?

TL;DR: I like it; minor comments on the commit message format (surprise). We 
should strive to provide consistent standards for it.


> ===Commit messages===
[...]
> If a bug is associated
> with a change, then it should be included in the summary line as
> <kbd>#nnnnnn</kbd> or likewise. 

..., for practical reasons in a format that is recognized by willikins. 
So, please DON'T do "... fixes #234987".

I suggest we recommend a plain "... bug 234567 ..."

So far, "bug x" in our repository by default refers to the Gentoo bugzilla, 
and it makes sense to stick with that.


> The tag part is included in the full commit log as an extension to the
> body. It consists of one or more lines consisting of key, followed by a
> colon and a space, followed by value. Git does not enforce any
> standardization of the keys, and the tag format is ''not'' meant for
> machine processing.
> 
> A few tags of common use are:
[...]
> ** <kbd>Bug: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>; — to
> reference a bug,
> ** <kbd>Closes: <nowiki>https://github.com/gentoo/gentoo/pull/NNNN</nowi
> ki></kbd>; — to automatically close a GitHub pull request,
> ** <kbd>Fixes: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>; —
> to indicate a fixed bug,

I would like to suggest that *if* such tags are used, we require that they 
should always contain a full URL to an issue tracker or code source.

This allows generic referencing of other bug trackers, leaves developers the 
option to auto-handle github-specific things, and still (for the purists) 
doesn't require mentioning Github in the GLEP.



-- 
Andreas K. Hüttel
dilfridge@gentoo.org
Gentoo Linux developer (council, perl, libreoffice)

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Rich Freeman]

On Tue, Jul 25, 2017 at 4:05 AM, Michał Górny <mgorny@gentoo.org> wrote:
>
> What do you think about it? Is there anything else that needs being
> covered?
>

FYI - if anybody does want to make any comments on the proposed
devmanual changes to implement the new tags please comment at:

https://github.com/gentoo/devmanual.gentoo.org/pull/72

For that matter, if you want to even know what the proposed changes
are you should also visit the link.

List replies seem to be discouraged.

I realize that some prefer to limit comments to media that are purely
open source.  I guess the FOSS Linux kernel provided /dev/null still
exists as an alternative.  Honestly, I'm not sure which of the options
are more likely to get read.

-- 
Rich

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Kristian Fiskerstrand]

[-- Attachment #1.1: Type: text/plain, Size: 595 bytes --]

On 09/08/2017 11:19 PM, Rich Freeman wrote:
> FYI - if anybody does want to make any comments on the proposed
> devmanual changes to implement the new tags please comment at:
> 
> https://github.com/gentoo/devmanual.gentoo.org/pull/72
> 
> For that matter, if you want to even know what the proposed changes
> are you should also visit the link.

This violates the gentoo social contract, please keep the discussion on
the mailing list

-- 
Kristian Fiskerstrand
OpenPGP keyblock reachable at hkp://pool.sks-keyservers.net
fpr:94CB AFDD 3034 5109 5618 35AA 0B7F 8B60 E3ED FAE3


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michał Górny]

W dniu pią, 08.09.2017 o godzinie 17∶19 -0400, użytkownik Rich Freeman
napisał:
> On Tue, Jul 25, 2017 at 4:05 AM, Michał Górny <mgorny@gentoo.org> wrote:
> > 
> > What do you think about it? Is there anything else that needs being
> > covered?
> > 
> 
> FYI - if anybody does want to make any comments on the proposed
> devmanual changes to implement the new tags please comment at:
> 
> https://github.com/gentoo/devmanual.gentoo.org/pull/72
> 
> For that matter, if you want to even know what the proposed changes
> are you should also visit the link.
> 
> List replies seem to be discouraged.
> 
> I realize that some prefer to limit comments to media that are purely
> open source.  I guess the FOSS Linux kernel provided /dev/null still
> exists as an alternative.  Honestly, I'm not sure which of the options
> are more likely to get read.
> 

TL;DR: Rich, I would really appreciate if you stopped the flamebaits.
I understand that you think you're doing Gentoo a favor but you're not.

The footers were discussed to death in this very thread. I've heard your
opinions. However, as far as I'm concerned (and as I've pointed out) you
did literally *nothing* to push your ideas forward for 2+ years.

Since I've done all the work, I've did it my way and for the reasons
I've explained multiple times. If you disagree, them I'm sorry but
in life you don't get to have everything your way. Especially if all you
do is complain and expect others to do the work for you.

I understand that you're unhappy and since you have no valid arguments,
all you can do is try to get more people to support you and shout.
Revive the bikeshed as many times as possible, try to make a lot of
noise and block changes. Worst case, you've blocked something you didn't
like. Best case, you're finally get others so discouraged that they'll
do things your way just so that you stop.

Rich, this is not a kindergarten. It's time you learn to lose,
and accept the consequences. If you can't do that, the door out is open,
and you're free to leave anytime you want.

-- 
Best regards,
Michał Górny

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Rich Freeman]

On Sat, Sep 9, 2017 at 3:47 AM, Michał Górny <mgorny@gentoo.org> wrote:
> W dniu pią, 08.09.2017 o godzinie 17∶19 -0400, użytkownik Rich Freeman
> napisał:
>>
>> FYI - if anybody does want to make any comments on the proposed
>> devmanual changes to implement the new tags please comment at:
>>
>> https://github.com/gentoo/devmanual.gentoo.org/pull/72
>>
>
> The footers were discussed to death in this very thread. I've heard your
> opinions. However, as far as I'm concerned (and as I've pointed out) you
> did literally *nothing* to push your ideas forward for 2+ years.
>

So, you read something from my comment that I didn't write, and
ignored the stuff I did write.

In part this is my fault, because I used sarcasm out of frustration,
and that wasn't conducive to communication.

To be clear:

I expressed my opinions earlier in the thread as you pointed out.

I have no expectation that my particular suggestion would be the one
implemented.  If I had felt THAT strongly about the implementation of
this I'd have put it on the Council agenda or something, or at least
would have discussed it in privately with you on IRC or something.
Instead, once I noticed that infra had implemented some of the tag
processing I switched to the format it appeared to be using in my
commits.

I don't expect anybody to wait for 100% consensus before doing
anything around here.  I think I've made that clear in plenty of
posts.  For significant changes there should be discussion on the
lists, and then the implementer should go forward with what they see
as the best implementation based on the feedback received.  If
somebody has a problem with it then it should be their duty to
escalate it and deal with it, not make the maintainer jump through
extra hoops.  Certainly we shouldn't be taking every change to the
Council.

My concern was entirely with the attitude expressed in your comment in
that pull request.  If you had written "I don't think we need to go
back to gentoo-dev for this one because this specific proposal was
part of what was already posted there and none of the feedback really
suggests a major problem with this" it wouldn't have bothered me,
because as the person doing the work I think you should be afforded a
bit more discretion, and this was part of your proposal.

Sometimes posting on -dev elicits opinions we disagree with from
people who haven't done any of the work.  That should neither paralyze
us, nor cause us to scoff at their suggestions.  They're just words.

-- 
Rich

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Daniel Campbell]

[-- Attachment #1.1: Type: text/plain, Size: 4082 bytes --]

On 09/09/2017 12:47 AM, Michał Górny wrote:
> W dniu pią, 08.09.2017 o godzinie 17∶19 -0400, użytkownik Rich Freeman
> napisał:
>> On Tue, Jul 25, 2017 at 4:05 AM, Michał Górny <mgorny@gentoo.org> wrote:
>>>
>>> What do you think about it? Is there anything else that needs being
>>> covered?
>>>
>>
>> FYI - if anybody does want to make any comments on the proposed
>> devmanual changes to implement the new tags please comment at:
>>
>> https://github.com/gentoo/devmanual.gentoo.org/pull/72
>>
>> For that matter, if you want to even know what the proposed changes
>> are you should also visit the link.
>>
>> List replies seem to be discouraged.
>>
>> I realize that some prefer to limit comments to media that are purely
>> open source.  I guess the FOSS Linux kernel provided /dev/null still
>> exists as an alternative.  Honestly, I'm not sure which of the options
>> are more likely to get read.
>>
> 
> TL;DR: Rich, I would really appreciate if you stopped the flamebaits.
> I understand that you think you're doing Gentoo a favor but you're not.
> 
> The footers were discussed to death in this very thread. I've heard your
> opinions. However, as far as I'm concerned (and as I've pointed out) you
> did literally *nothing* to push your ideas forward for 2+ years.
> 
> Since I've done all the work, I've did it my way and for the reasons
> I've explained multiple times. If you disagree, them I'm sorry but
> in life you don't get to have everything your way. Especially if all you
> do is complain and expect others to do the work for you.
> 
> I understand that you're unhappy and since you have no valid arguments,
> all you can do is try to get more people to support you and shout.
> Revive the bikeshed as many times as possible, try to make a lot of
> noise and block changes. Worst case, you've blocked something you didn't
> like. Best case, you're finally get others so discouraged that they'll
> do things your way just so that you stop.
> 
> Rich, this is not a kindergarten. It's time you learn to lose,
> and accept the consequences. If you can't do that, the door out is open,
> and you're free to leave anytime you want.
> 
This behavior is not befitting Gentoo leadership. Limiting commentary to
a walled garden outside Gentoo control violates one of our goals
(independence), and the incendiary retorts are no more mature than the
behavior you're criticizing. Nothing will change in the way people
respond to you until you learn how to treat others.

By all means, I'm glad we're seeing some action on which tags to settle
with. It's been a mess of confusion ("which tags do I use? Will this
tick someone off?", etc), and will be easier to build on once we figure
out the tags that'll work best. It'll be awesome to get automatic bug
closing from a commit, and I suspect it'll bring a lot of good. Settling
on tags allows us to automate more. However, as a Council member, the
Gentoo community looks to you and your behavior as an example. Is this
the example you want to set for our community?

On the GitHub Issue, you called this mailing list "completely useless"
[1], and then you sent your message above a little later. Would you want
to work with someone who talks to you the way you treated Rich?

None of this bickering is motivating or inspiring to those who read it,
and leadership should know better than to stoop to this level publicly.
You will not get more developer activity, agreement, cooperation, or
contribution by berating your fellow developers. In fact, Gentoo is
known for its bickering developer community. You are in a position to
change that. You asserted in #gentoo-trustees that the Council *is*
Gentoo's leadership.

Is this your brand of leadership?

~zlg

[1] https://dev.gentoo.org/~zlg/useless.png

(screenshotted since GitHub conversations can be curated.)
-- 
Daniel Campbell - Gentoo Developer, Trustee, Treasurer
OpenPGP Key: 0x1EA055D6 @ hkp://keys.gnupg.net
fpr: AE03 9064 AE00 053C 270C  1DE4 6F7A 9091 1EA0 55D6


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Michał Górny]

W dniu nie, 10.09.2017 o godzinie 00∶39 -0700, użytkownik Daniel
Campbell napisał:
> On 09/09/2017 12:47 AM, Michał Górny wrote:
> > W dniu pią, 08.09.2017 o godzinie 17∶19 -0400, użytkownik Rich Freeman
> > napisał:
> > > On Tue, Jul 25, 2017 at 4:05 AM, Michał Górny <mgorny@gentoo.org> wrote:
> > > > 
> > > > What do you think about it? Is there anything else that needs being
> > > > covered?
> > > > 
> > > 
> > > FYI - if anybody does want to make any comments on the proposed
> > > devmanual changes to implement the new tags please comment at:
> > > 
> > > https://github.com/gentoo/devmanual.gentoo.org/pull/72
> > > 
> > > For that matter, if you want to even know what the proposed changes
> > > are you should also visit the link.
> > > 
> > > List replies seem to be discouraged.
> > > 
> > > I realize that some prefer to limit comments to media that are purely
> > > open source.  I guess the FOSS Linux kernel provided /dev/null still
> > > exists as an alternative.  Honestly, I'm not sure which of the options
> > > are more likely to get read.
> > > 
> > 
> > TL;DR: Rich, I would really appreciate if you stopped the flamebaits.
> > I understand that you think you're doing Gentoo a favor but you're not.
> > 
> > The footers were discussed to death in this very thread. I've heard your
> > opinions. However, as far as I'm concerned (and as I've pointed out) you
> > did literally *nothing* to push your ideas forward for 2+ years.
> > 
> > Since I've done all the work, I've did it my way and for the reasons
> > I've explained multiple times. If you disagree, them I'm sorry but
> > in life you don't get to have everything your way. Especially if all you
> > do is complain and expect others to do the work for you.
> > 
> > I understand that you're unhappy and since you have no valid arguments,
> > all you can do is try to get more people to support you and shout.
> > Revive the bikeshed as many times as possible, try to make a lot of
> > noise and block changes. Worst case, you've blocked something you didn't
> > like. Best case, you're finally get others so discouraged that they'll
> > do things your way just so that you stop.
> > 
> > Rich, this is not a kindergarten. It's time you learn to lose,
> > and accept the consequences. If you can't do that, the door out is open,
> > and you're free to leave anytime you want.
> > 
> 
> This behavior is not befitting Gentoo leadership. Limiting commentary to
> a walled garden outside Gentoo control violates one of our goals
> (independence), and the incendiary retorts are no more mature than the
> behavior you're criticizing. Nothing will change in the way people
> respond to you until you learn how to treat others.
> 
> By all means, I'm glad we're seeing some action on which tags to settle
> with. It's been a mess of confusion ("which tags do I use? Will this
> tick someone off?", etc), and will be easier to build on once we figure
> out the tags that'll work best. It'll be awesome to get automatic bug
> closing from a commit, and I suspect it'll bring a lot of good. Settling
> on tags allows us to automate more. However, as a Council member, the
> Gentoo community looks to you and your behavior as an example. Is this
> the example you want to set for our community?
> 
> On the GitHub Issue, you called this mailing list "completely useless"
> [1], and then you sent your message above a little later. Would you want
> to work with someone who talks to you the way you treated Rich?

Yes, I did call it useless *multiple times*, and I've pointed out
the problems. Considering they were ignored and the quality of
the mailing list hasn't improved, this statement still stands.

Rich should have talked to me if he had problems with understanding my
comment or missed the context to it. What he did instead is beginning
a public stone throwing session. This is not a kind of behavior I am
going to accept, or respond kindly to.

It's elementary. If you have a problem with me, talk to me first. Not go
pointing fingers and shouting 'this person is bad'.

> None of this bickering is motivating or inspiring to those who read it,
> and leadership should know better than to stoop to this level publicly.
> You will not get more developer activity, agreement, cooperation, or
> contribution by berating your fellow developers. In fact, Gentoo is
> known for its bickering developer community. You are in a position to
> change that. You asserted in #gentoo-trustees that the Council *is*
> Gentoo's leadership.
> 
> Is this your brand of leadership?
> 
> ~zlg
> 
> [1] https://dev.gentoo.org/~zlg/useless.png
> 
> (screenshotted since GitHub conversations can be curated.)

I'm not going to answer to your political propaganda. We don't need more
politicians like you in Gentoo. We need actual people who do stuff
rather than talk about theory to the point when everybody is so tired
nobody wants to do anything anymore.


-- 
Best regards,
Michał Górny

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Daniel Campbell]

[-- Attachment #1.1: Type: text/plain, Size: 12728 bytes --]

On 09/10/2017 02:34 AM, Michał Górny wrote:
> W dniu nie, 10.09.2017 o godzinie 00∶39 -0700, użytkownik Daniel
> Campbell napisał:
>> On 09/09/2017 12:47 AM, Michał Górny wrote:
>>> W dniu pią, 08.09.2017 o godzinie 17∶19 -0400, użytkownik Rich Freeman
>>> napisał:
>>>> On Tue, Jul 25, 2017 at 4:05 AM, Michał Górny <mgorny@gentoo.org> wrote:
>>>>>
>>>>> What do you think about it? Is there anything else that needs being
>>>>> covered?
>>>>>
>>>>
>>>> FYI - if anybody does want to make any comments on the proposed
>>>> devmanual changes to implement the new tags please comment at:
>>>>
>>>> https://github.com/gentoo/devmanual.gentoo.org/pull/72
>>>>
>>>> For that matter, if you want to even know what the proposed changes
>>>> are you should also visit the link.
>>>>
>>>> List replies seem to be discouraged.
>>>>
>>>> I realize that some prefer to limit comments to media that are purely
>>>> open source.  I guess the FOSS Linux kernel provided /dev/null still
>>>> exists as an alternative.  Honestly, I'm not sure which of the options
>>>> are more likely to get read.
>>>>
>>>
>>> TL;DR: Rich, I would really appreciate if you stopped the flamebaits.
>>> I understand that you think you're doing Gentoo a favor but you're not.
>>>
>>> The footers were discussed to death in this very thread. I've heard your
>>> opinions. However, as far as I'm concerned (and as I've pointed out) you
>>> did literally *nothing* to push your ideas forward for 2+ years.
>>>
>>> Since I've done all the work, I've did it my way and for the reasons
>>> I've explained multiple times. If you disagree, them I'm sorry but
>>> in life you don't get to have everything your way. Especially if all you
>>> do is complain and expect others to do the work for you.
>>>
>>> I understand that you're unhappy and since you have no valid arguments,
>>> all you can do is try to get more people to support you and shout.
>>> Revive the bikeshed as many times as possible, try to make a lot of
>>> noise and block changes. Worst case, you've blocked something you didn't
>>> like. Best case, you're finally get others so discouraged that they'll
>>> do things your way just so that you stop.
>>>
>>> Rich, this is not a kindergarten. It's time you learn to lose,
>>> and accept the consequences. If you can't do that, the door out is open,
>>> and you're free to leave anytime you want.
>>>
>>
>> This behavior is not befitting Gentoo leadership. Limiting commentary to
>> a walled garden outside Gentoo control violates one of our goals
>> (independence), and the incendiary retorts are no more mature than the
>> behavior you're criticizing. Nothing will change in the way people
>> respond to you until you learn how to treat others.
>>
>> By all means, I'm glad we're seeing some action on which tags to settle
>> with. It's been a mess of confusion ("which tags do I use? Will this
>> tick someone off?", etc), and will be easier to build on once we figure
>> out the tags that'll work best. It'll be awesome to get automatic bug
>> closing from a commit, and I suspect it'll bring a lot of good. Settling
>> on tags allows us to automate more. However, as a Council member, the
>> Gentoo community looks to you and your behavior as an example. Is this
>> the example you want to set for our community?
>>
>> On the GitHub Issue, you called this mailing list "completely useless"
>> [1], and then you sent your message above a little later. Would you want
>> to work with someone who talks to you the way you treated Rich?
> 
> Yes, I did call it useless *multiple times*, and I've pointed out
> the problems. Considering they were ignored and the quality of
> the mailing list hasn't improved, this statement still stands.
> 
> Rich should have talked to me if he had problems with understanding my
> comment or missed the context to it. What he did instead is beginning
> a public stone throwing session. This is not a kind of behavior I am
> going to accept, or respond kindly to.
> 
> It's elementary. If you have a problem with me, talk to me first. Not go
> pointing fingers and shouting 'this person is bad'.

That's a good policy, one most of us can agree with I think. Sarcasm
isn't often understood (or appreciated) by all, but Rich's comment
really didn't do anything except highlight how discussion was being
moved. This creates a divide in the information and discussion available
to other developers. You and others are free to do this, but others are
right to criticize it also. Calling an entire community "useless" is not
going to magically make it better.

> 
>> None of this bickering is motivating or inspiring to those who read it,
>> and leadership should know better than to stoop to this level publicly.
>> You will not get more developer activity, agreement, cooperation, or
>> contribution by berating your fellow developers. In fact, Gentoo is
>> known for its bickering developer community. You are in a position to
>> change that. You asserted in #gentoo-trustees that the Council *is*
>> Gentoo's leadership.
>>
>> Is this your brand of leadership?
>>
>> ~zlg
>>
>> [1] https://dev.gentoo.org/~zlg/useless.png
>>
>> (screenshotted since GitHub conversations can be curated.)
> 
> I'm not going to answer to your political propaganda. We don't need more
> politicians like you in Gentoo. We need actual people who do stuff
> rather than talk about theory to the point when everybody is so tired
> nobody wants to do anything anymore.
> 
> 
I'm not looking for political propaganda. What would I gain from it? I
don't really have any strong connections here. In fact I'm probably
ticking a few people off. I'm calling your practices out for what they
are, since nobody else appears willing or able to. It's flat-out
dishonest to complain about a mailing list on one site, then
deliberately add flames to the fire less than a day later on the very
list you complained about. You are contributing to the very thing you
claim to detest. I don't see that as political, because it affects the
work that you, I, and other Gentoo devs do. It damages relationships
between developers, and if something isn't done about it, Gentoo will
continue falling into irrelevance because we can't get our ship to sail
smoothly. We all have the ability to improve this, and I gain nothing by
writing this e-mail.

With this particular issue (git commit tags), I understand bikeshed will
happen. Seeking to divide the community between your hand-picked "these
people do things (I like), so they're better than the others" and
everyone else is destructive to our distribution. It's akin to building
a second bikeshed because you didn't like the color of the first one.
Why should anyone work with you if you treat them like trash? Because
your hands are in many cookie jars? Because you're a Council member?
Because you're competent? Libre software projects cannot exist purely in
a technical environment as long as there is a human element. You need
social merit, and social skill, to get anywhere with collaboration, or
you will end up with too much work and not enough time (because you've
driven everyone away). That is the beginning of a distro's downward
curve -- when collaboration is no longer enjoyable to those who are part
of the group. You and I don't know each other personally, but based on
where I've seen your name, it's clear you have plenty of technical
merit. And some people are your friends (I assume), so you're not
bankrupt in social merit, either. Why do you feel entitled to treat
others in this fashion? You are already an established member of our
distro, and there's no need to lash out at others.

Note that I didn't claim that I was good at the social part. Most of us
could do better, myself included. Many programmers are gruff and
insolent, so it's difficult to learn from them. I have trouble with
people who are quick to belittle one's intelligence for making mistakes,
so it affects my ability to get good feedback. I don't fancy being
abused, having lived through enough of it in my personal life, so I
don't seek out those who will abuse me. As a result, I contribute less
to Gentoo than I'd like to. I suspect I'm not alone in that.

I'm not saying we should flatter each other and put on kid gloves. I'm
saying we should treat each other as reasonable adults working on
software to the betterment of everyone involved. A big part of Gentoo's
problems are in how it deals with developers making mistakes, or the
poor accessibility of decisions or processes that are often discarded as
"this was already covered", often without links to rationale. QA, for
example, means jack if its information is not widely accessible,
discussed, and enforced on a consistent basis. I can count on one hand
the number of useful QA docs I've managed to find.

Does that mean QA as a whole is crap? No. It means that there is a
disconnect between those who write the standards and those who need to
write *to* those standards. Fix that, and your hatred of "do nothing"s
will fix itself because your fellow developers will have better
resources to educate themselves with. It has the knock-on effect of
convenience: if someone makes a dumb mistake, someone can tell them what
they screwed up and link to something that will educate them. IRC bots
do this all the time, especially in #vim, so it's not like this is some
insurmountable hurdle. Until we get to such a point, it's the
responsibility of the more experienced developers to assist those they
perceive as "bad" to improve, or their criticism has no weight or
credibility. Again, that doesn't mean hand-holding, coddling, or
anything of the sort. It means getting people up to speed and
understanding that mistakes happen due to incomplete or conflicting
information, not malice. If you take a look at other areas of life,
you'll see that it's how humanity retains its collective knowledge:
passing it down to the less-experienced. Computer science wouldn't have
gotten anywhere if the findings and techniques weren't shared. The same
is true of Gentoo.

A fine example is a recent review I had with floppym in #gentoo-python.
To be honest, I was expecting to deal with berating and belittlement,
like what happens when I deal with you. But I reserved my judgment and
went ahead anyway. floppym was a big surprise. I learned more from him
in 10-20 minutes than I have in most other reviews, and now I know more
so I can avoid making those mistakes in the future. (I kept notes) I
thanked him for his time and willingness to teach me a few things, and
Gentoo improved a little bit that day, both technically and socially. I
hope the experience was as pleasant for him.

(To clarify, I recall floppym and I having a minor tiff months ago. We
both overcame that history to improve Gentoo. If you're reading this,
Mike, thanks again.)

Situations like the above are probably not that special; I assume it
happens a lot. But typically, nobody in Gentoo really points that stuff
out and congratulates it. I never read about how developers X, Y, and Z
pulled together and made a useful feature in Gentoo possible. I never
read about the work arch testers and CI and infra put into making our
lives smoother. I don't see any stories told about how things came to be
for Gentoo. It's shrouded in documents spread across all of infra --
assuming it exists in the first place -- and as a result, the hard work
people put into this distro doesn't get a lot of attention. That could
be a large source of the general discontentment among some of us.

Maybe we should give our developers more credit when they do great work
instead of hating on them when they screw up. This method focuses on the
good instead of the bad, providing positive reinforcement, which is
proven to work in psychology. People like to know they're contributing
to something and making something better. If they're not, they want to
know *why* their solution is broken and *how* to fix it, so they can do
better.

If you aren't interested in any of that, I have to wonder why you chose
to run for a role that deals just as much with people as it does code.
If you have the inclination, I'd be willing to discuss that in another
thread, private or public. I've gone far enough off-topic already.

(Apologies for verbosity. It's necessary to ensure I don't get
misunderstood.)

~zlg
-- 
Daniel Campbell - Gentoo Developer, Trustee, Treasurer
OpenPGP Key: 0x1EA055D6 @ hkp://keys.gnupg.net
fpr: AE03 9064 AE00 053C 270C  1DE4 6F7A 9091 1EA0 55D6


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [gentoo-dev] [RFC pre-GLEP] Gentoo Git Workflow

[Dean Stephens]

On 09/10/17 18:13, Daniel Campbell wrote:
> I'm not looking for political propaganda. What would I gain from it? I
> don't really have any strong connections here. In fact I'm probably
> ticking a few people off. I'm calling your practices out for what they
> are, since nobody else appears willing or able to. It's flat-out
> dishonest to complain about a mailing list on one site, then
> deliberately add flames to the fire less than a day later on the very
> list you complained about. You are contributing to the very thing you
> claim to detest. I don't see that as political, because it affects the
> work that you, I, and other Gentoo devs do. It damages relationships
> between developers, and if something isn't done about it, Gentoo will
> continue falling into irrelevance because we can't get our ship to sail
> smoothly. We all have the ability to improve this, and I gain nothing by
> writing this e-mail.
> 
At this point, the question comes down to whether ComRel would sanction
a sitting Council member and whether it has reached the point at which
discovering the answer in practical reality is needed, especially
considering the virtually guaranteed backlash should that answer turn
out to be negative.

While I realize that positive reinforcement is generally a more
effective training methodology, it seems impractical in this case.