Re: [gentoo-dev] Re: [PATCH v2 17/19] ebuild-writing/misc-files: remove ChangeLog section #485314

[Ulrich Mueller]

> On Tue, 26 Jan 2016, Göktürk Yüksek wrote:

> Ulrich Mueller:
>> The devmanual is the one central place where our development
>> workflow should be documented, not some random wiki page.
>> 
> If the most up-to-date information is on the wiki, constantly
> updating devmanual to match the wiki creates unnecessary maintenance
> burden.

The point is that any information that constitutes policy should be
traceable, e.g. there should be a bug or a patch should be posted to
the mailing lists.

> Related to my point above, looks like the git workflow is still in
> the process of making. I expect that some discussion will continue
> to take place in the future. We can always fix the other parts of
> the devmanual and come back to this.

I beg to differ. Apart from some small details, things have settled.
Looking at the history of the wiki page, there was quite some activity
in the two months following the switch to git, but very little after.

> Is it possible to merge this changeset as is while the workflow
> matures, or should I go for a round 3?

I'd prefer a round 3, including Michael's suggestions at least. That
is, include the "Commit message format" subsection from the wiki page
(or even the "Commit policy" section; it is not much longer).

Ulrich


pgp0RVkHvkWFb.pgp
Description: PGP signature

Re: [gentoo-dev] Re: [PATCH v2 17/19] ebuild-writing/misc-files: remove ChangeLog section #485314

[Göktürk Yüksek]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA512

Ulrich Mueller:
>> On Sun, 24 Jan 2016, Michael Orlitzky wrote:
> 
>> The ChangeLog page is nonsense as-is, and removing it makes the 
>> devmanual better. Afterwards, if someone wants to take the commit
>> message guidelines from the wiki and merge them with the old
>> ChangeLog tips, great. There's only two things worth salvaging
>> from the ChangeLog page. Here's the combined list:
> 
>> 1. Everything from the Git workflow wiki page "Commit message 
>> format" section.
> 
> I would say not only that section, but most of the page. The 
> devmanual is the one central place where our development workflow 
> should be documented, not some random wiki page.
> 
If the most up-to-date information is on the wiki, constantly updating
devmanual to match the wiki creates unnecessary maintenance burden.

>> 2. Mention the "Gentoo-Bug:" identifier.
> 
> Right. (But had we settled for "Gentoo-Bug:"? IIRC, last time this 
> was discussed there was no consensus.)
> 
Related to my point above, looks like the git workflow is still in the
process of making. I expect that some discussion will continue to take
place in the future. We can always fix the other parts of the
devmanual and come back to this.

Is it possible to merge this changeset as is while the workflow
matures, or should I go for a round 3?

>> Using "bug #12345" in the commit message itself causes trouble. 
>> If you word-wrap on the "#12345", it will silently clobber the 
>> message.
> 
> That's one of the reasons why I have 'commentchar = ";"' in my 
> .gitconfig file. (Not sure if that option would be worth mentioning
> in our documentation, though.)
> 
>> [...]
> 
> Ulrich
> 

- --
gokturk

-BEGIN PGP SIGNATURE-

iQEcBAEBCgAGBQJWqEU2AAoJEIT4AuXAiM4zwCAH/3q8FQB+zX0q1kuXjJfYnF3j
IvJ2uKjuHMfbSAoGy2bUGEEhsvXGpNTmLv7vDIiHILCeLR0mD1eAmWHuJjjUSmJx
PyK6kAPaXX++E5aZ9gRuXqNFSGqiNx3oPvzQs0SH6vXgVec8fpmRk6y/Dg2r20Am
hfJLPIeD8Z9Vf/0wM7EcjiS3eVYrTnYCX+aGAKpgk74zKHcnHTL9S77no0Lemby1
vlCK9ceouVd6OYdDcvjNg73umlci7JIenCZCU3nagloGwvH6XDFWdGkWSRLQ0G7T
DoZlysM2Litafjr7NgyQ7R8xp1HnR+tmWfY26urIPd4rKU+aA05kPnQiTjgKTHo=
=UDYD
-END PGP SIGNATURE-

Re: [gentoo-dev] Re: [PATCH v2 17/19] ebuild-writing/misc-files: remove ChangeLog section #485314

[Ulrich Mueller]

> On Sun, 24 Jan 2016, Michael Orlitzky wrote:

> The ChangeLog page is nonsense as-is, and removing it makes the
> devmanual better. Afterwards, if someone wants to take the commit
> message guidelines from the wiki and merge them with the old ChangeLog
> tips, great. There's only two things worth salvaging from the ChangeLog
> page. Here's the combined list:

>   1. Everything from the Git workflow wiki page "Commit message format"
>  section.

I would say not only that section, but most of the page. The devmanual
is the one central place where our development workflow should be
documented, not some random wiki page.

>   2. Mention the "Gentoo-Bug:" identifier.

Right. (But had we settled for "Gentoo-Bug:"? IIRC, last time this was
discussed there was no consensus.)

>  Using "bug #12345" in the commit message itself causes trouble.
>  If you word-wrap on the "#12345", it will silently clobber the
>  message.

That's one of the reasons why I have 'commentchar = ";"' in my
.gitconfig file. (Not sure if that option would be worth mentioning
in our documentation, though.)

> [...]

Ulrich


pgpCIOxORuqZQ.pgp
Description: PGP signature

Re: [gentoo-dev] Re: [PATCH v2 17/19] ebuild-writing/misc-files: remove ChangeLog section #485314

[Michael Orlitzky]

On 01/24/2016 07:43 PM, Ulrich Mueller wrote:
>> On Sun, 24 Jan 2016, Gokturk Yuksek wrote:
> 
>> From: Michael Orlitzky 
> 
>> The ChangeLog section under misc-files is misleading now that our main
>> repository has been switched to git (and we no longer have
>> ChangeLogs). Remove the ebuild-writing/misc-files/changelog page.
> 
> Most of that section contains information that will still apply, even
> if it no longer goes into a ChangeLog but a into a git commit message.
> 
> Therefore the section shouldn't be removed, but rather be updated.
> 

We will eventually need a "Commit Messages" page, but in my opinion the
bar for these sorts of patches should be "does it make things better?"
If so, merge it, and if you want to improve the result, do that.
Otherwise nothing gets done.

The ChangeLog page is nonsense as-is, and removing it makes the
devmanual better. Afterwards, if someone wants to take the commit
message guidelines from the wiki and merge them with the old ChangeLog
tips, great. There's only two things worth salvaging from the ChangeLog
page. Here's the combined list:

  1. Everything from the Git workflow wiki page "Commit message format"
 section.

  2. Mention the "Gentoo-Bug:" identifier. Using "bug #12345" in the
 commit message itself causes trouble. If you word-wrap on the
 "#12345", it will silently clobber the message.

  3. When including user-submitted ebuilds or patches, you should
 credit the user with his full name and email address (or
 whatever he uses to identify himself on bugzilla — some users
 prefer to be known only by a nickname).

  3.i. But use the "Reported-By:", "Suggested-By:", etc. mentioned on
   the wiki.

  4. If you are changing keywords, make sure you clearly state what
 keywords you add or remove.

The bad examples at the end of the ChangeLog page are still bad, but the
good examples are now bad too. There's not much worth saving.

[gentoo-dev] Re: [PATCH v2 17/19] ebuild-writing/misc-files: remove ChangeLog section #485314

[Ulrich Mueller]

> On Sun, 24 Jan 2016, Gokturk Yuksek wrote:

> From: Michael Orlitzky 

> The ChangeLog section under misc-files is misleading now that our main
> repository has been switched to git (and we no longer have
> ChangeLogs). Remove the ebuild-writing/misc-files/changelog page.

Most of that section contains information that will still apply, even
if it no longer goes into a ChangeLog but a into a git commit message.

Therefore the section shouldn't be removed, but rather be updated.

Ulrich


pgponwQMV0Kg8.pgp
Description: PGP signature

[gentoo-dev] Re: [PATCH v2 17/19] ebuild-writing/misc-files: remove ChangeLog section #485314

[Göktürk Yüksek]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA512

Ulrich Mueller:
>> On Sun, 24 Jan 2016, Gokturk Yuksek wrote:
> 
>> From: Michael Orlitzky 
> 
>> The ChangeLog section under misc-files is misleading now that
>> our main repository has been switched to git (and we no longer
>> have ChangeLogs). Remove the ebuild-writing/misc-files/changelog 
>> page.
> 
> Most of that section contains information that will still apply, 
> even if it no longer goes into a ChangeLog but a into a git commit 
> message.
> 
> Therefore the section shouldn't be removed, but rather be updated.
> 
What if we extract the information regarding writing good commit
messages and move it under ebuild-maintenance, possibly as a new
subsection or under the subsection "Git Commit Policy"?

I agree that the information there is valuable but a better
documentation is available on the git workflow wiki[1]. We can
alternatively insert a link to the wiki page instead or import the
same information. But keeping the two in sync will be problematic.

> Ulrich
> 

[1] https://wiki.gentoo.org/wiki/Gentoo_git_workflow#Commit_message_form
at

- --
gokturk

-BEGIN PGP SIGNATURE-

iQEcBAEBCgAGBQJWpXQZAAoJEIT4AuXAiM4zgxIH/AwU3j8TMpYB7m+1Eeyg19wL
nuY2YwDaev2KnEN8tmhqksCjyRJM9MvZpPXUfIvtaQBAFknYKPP3cI7leLQaQvUD
pu0bMjfv3NIEM8Ux9tuWfeTYaBmnqOi1k9aFkCwIrpktDDjgz90KBq9ua40V1gEz
aSAjaMZEs4YCZY/lTsgudPYCEQIiOkNfeC0riSSPnvG4Mp+LxZr3wcaudlFE57FZ
hkNkjsTsLCqjmNCxI8FNYDiWqA+uueSkEWan3xjJV3bl8iJc82lcZoRayO5cwuDU
CNNpDBABw9YDA6IrBNxpq/MxunKhdc2RuUFQmsw9I69WIWxwS555sxlMGugQGQ8=
=9AN4
-END PGP SIGNATURE-