[gentoo-portage-dev] [PATCH] Document bugzilla workflow

[gentoo-portage-dev] [PATCH] Document bugzilla workflow

[SebastianLuther]

From: Sebastian Luther <SebastianLuther@gmx.de>

---
 DEVELOPING | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/DEVELOPING b/DEVELOPING
index a2c9ae1..7a97d3d 100644
--- a/DEVELOPING
+++ b/DEVELOPING
@@ -161,6 +161,34 @@ somewhat annoying because the import line needs to be modified when functions
 are needed and often unused functions are left in the import line until someone
 comes along with a linter to clean up (does not happen often).
 
+Bugzilla
+--------
+
+There always exists a tracker bug, named:
+"[Tracker] sys-apps/portage-<next version>".
+
+This bug is renamed from X.Y.Z to X.Y.Z+1 after a release, until
+it gets closed when Y changes and a new one is opened.
+
+Whenever a commit for a specific bug is made to the git repo,
+the corresponding bug gets changed in the following ways:
+* InVCS is added to Keywords
+* The bug is marked as blocking the tracker for the next version
+* A comment is added saying: This is fixed in git: <url to commit>
+(note that the bug stays open)
+
+After a release all open bugs blocking the tracker are closed
+with the comment "This is fixed in <version>.".
+
+For individual open bugs it is encouraged to set UNCONFIRMED,
+CONFIRMED or IN_PROGESS as appropriate.
+
+There are a number of bugs named "[TRACKER] *" that collect bugs
+for specific topics. Confirmed bugs should be marked as blocking
+these tracker bugs if appropriate.
+
+It is encouraged to set the alias field for frequently used bugs.
+
 
 Releases
 --------
-- 
1.8.3.2

Re: [gentoo-portage-dev] [PATCH] Document bugzilla workflow

[Tom Wijsman]

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

On Wed,  8 Jan 2014 19:25:19 +0100
SebastianLuther@gmx.de wrote:

> From: Sebastian Luther <SebastianLuther@gmx.de>

Can you fix your git config too? See vapier's feedback on creffet.

> +Bugzilla
> +--------

More discussion is needed before we should add this; at least I think
it should be brought up during the meeting this Sunday, because we've
barely had feedback and at least one suggestion doesn't appear
discussed and/or incorporated.

I've commented on the suggestion by dol-sen which I like the most;
especially the assignment part, I think it also contains some other neat
additions.

Besides that, I'll comment my thoughts on some of the other parts here:

> +There always exists a tracker bug, named:
> +"[Tracker] sys-apps/portage-<next version>".
> +
> +This bug is renamed from X.Y.Z to X.Y.Z+1 after a release, until
> +it gets closed when Y changes and a new one is opened.

While this spares out on tracker bugs, we lose the ability to track
which bugs were fixed in which version, unless we enforce that all bug
numbers get to be listed in the ChangeLog; do we have a policy for that?

> +Whenever a commit for a specific bug is made to the git repo,
> +the corresponding bug gets changed in the following ways:
> +* InVCS is added to Keywords
> +* The bug is marked as blocking the tracker for the next version
> +* A comment is added saying: This is fixed in git: <url to commit>
> +(note that the bug stays open)

+1

> +After a release all open bugs blocking the tracker are closed
> +with the comment "This is fixed in <version>.".

+1

> +For individual open bugs it is encouraged to set UNCONFIRMED,
> +CONFIRMED or IN_PROGESS as appropriate.

What is "as appropriate"? As I mentioned, this needs more discussion;
please keep this the way it was, it makes the tracker bug more useful.

> +There are a number of bugs named "[TRACKER] *" that collect bugs
> +for specific topics. Confirmed bugs should be marked as blocking
> +these tracker bugs if appropriate.

For clarity, it should be mentioned that this does not mean to block
the tracker for the next version; this could be misinterpreted.

> +It is encouraged to set the alias field for frequently used bugs.

Yes, but please set it to something specific enough; I'm tired of
searching for a random word and get into one or another old bug.

-- 
With kind regards,

Tom Wijsman (TomWij)
Gentoo Developer

E-mail address  : TomWij@gentoo.org
GPG Public Key  : 6D34E57D
GPG Fingerprint : C165 AF18 AB4C 400B C3D2  ABF0 95B2 1FCD 6D34 E57D

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

Re: [gentoo-portage-dev] [PATCH] Document bugzilla workflow

[Sebastian Luther]

Am 15.01.2014 04:11, schrieb Tom Wijsman:
> On Wed,  8 Jan 2014 19:25:19 +0100
> SebastianLuther@gmx.de wrote:
> 
>> From: Sebastian Luther <SebastianLuther@gmx.de>
> 
> Can you fix your git config too? See vapier's feedback on creffet.

I'll take a look.

> 
>> +Bugzilla
>> +--------
> 
> More discussion is needed before we should add this; at least I think
> it should be brought up during the meeting this Sunday, because we've
> barely had feedback and at least one suggestion doesn't appear
> discussed and/or incorporated.

I send the first mail with this wording 8 days ago. Enough time to
comment on it. I'd prefer to discuss it on the list.

> 
> I've commented on the suggestion by dol-sen which I like the most;
> especially the assignment part, I think it also contains some other neat
> additions.
> 
> Besides that, I'll comment my thoughts on some of the other parts here:
> 
>> +There always exists a tracker bug, named:
>> +"[Tracker] sys-apps/portage-<next version>".
>> +
>> +This bug is renamed from X.Y.Z to X.Y.Z+1 after a release, until
>> +it gets closed when Y changes and a new one is opened.
> 
> While this spares out on tracker bugs, we lose the ability to track
> which bugs were fixed in which version, 

That's not true. Just look at the tracker for 2.2.9. Between the renames
of the tracker you'll see which bug has been marked as blocking. These
are the fixed ones.

unless we enforce that all bug
> numbers get to be listed in the ChangeLog; do we have a policy for that?

The numbers go into the ebuild changelog, but I don't think that's
written down somewhere (/me looks at dol-sen).

> 
>> +Whenever a commit for a specific bug is made to the git repo,
>> +the corresponding bug gets changed in the following ways:
>> +* InVCS is added to Keywords
>> +* The bug is marked as blocking the tracker for the next version
>> +* A comment is added saying: This is fixed in git: <url to commit>
>> +(note that the bug stays open)
> 
> +1
> 
>> +After a release all open bugs blocking the tracker are closed
>> +with the comment "This is fixed in <version>.".
> 
> +1
> 
>> +For individual open bugs it is encouraged to set UNCONFIRMED,
>> +CONFIRMED or IN_PROGESS as appropriate.
> 
> What is "as appropriate"? As I mentioned, this needs more discussion;
> please keep this the way it was, it makes the tracker bug more useful.

The "way it was" is to not care about them at all. There was no
agreement on the the other thread if these things should be used or not.
So I left it vague so everyone could use it, but they are not forced to.

> 
>> +There are a number of bugs named "[TRACKER] *" that collect bugs
>> +for specific topics. Confirmed bugs should be marked as blocking
>> +these tracker bugs if appropriate.
> 
> For clarity, it should be mentioned that this does not mean to block
> the tracker for the next version; this could be misinterpreted.

Considering that the tracker gets renamed, I'm not sure what you mean here.

> 
>> +It is encouraged to set the alias field for frequently used bugs.
> 
> Yes, but please set it to something specific enough; I'm tired of
> searching for a random word and get into one or another old bug.
> 
Most likely candidates are the trackers.

Re: [gentoo-portage-dev] [PATCH] Document bugzilla workflow

[Tom Wijsman]

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

On Wed, 15 Jan 2014 07:29:19 +0100
Sebastian Luther <SebastianLuther@gmx.de> wrote:

> Am 15.01.2014 04:11, schrieb Tom Wijsman:
>
> > More discussion is needed before we should add this; at least I
> > think it should be brought up during the meeting this Sunday,
> > because we've barely had feedback and at least one suggestion
> > doesn't appear discussed and/or incorporated.
> 
> I send the first mail with this wording 8 days ago. Enough time to
> comment on it. I'd prefer to discuss it on the list.

Yes, but not all comments were discussed yet, therefore (dis)agreement
on them is missing; and this last thing rather became a topic of
discussion due to the work clashes that we saw happen twice.

> >> +There always exists a tracker bug, named:
> >> +"[Tracker] sys-apps/portage-<next version>".
> >> +
> >> +This bug is renamed from X.Y.Z to X.Y.Z+1 after a release, until
> >> +it gets closed when Y changes and a new one is opened.
> > 
> > While this spares out on tracker bugs, we lose the ability to track
> > which bugs were fixed in which version, 
> 
> That's not true. Just look at the tracker for 2.2.9. Between the
> renames of the tracker you'll see which bug has been marked as
> blocking. These are the fixed ones.

Good point, thanks; a small problem is when bugs get reopened, but I
suppose this wouldn't happen too often to be a big problem.

> unless we enforce that all bug
> > numbers get to be listed in the ChangeLog; do we have a policy for
> > that?
> 
> The numbers go into the ebuild changelog, but I don't think that's
> written down somewhere (/me looks at dol-sen).

Yes, I see some commit messages not refer to bugs which is something we
will want to avoid; think this might need to go into the commit policy.

> >> +For individual open bugs it is encouraged to set UNCONFIRMED,
> >> +CONFIRMED or IN_PROGESS as appropriate.
> > 
> > What is "as appropriate"? As I mentioned, this needs more
> > discussion; please keep this the way it was, it makes the tracker
> > bug more useful.
> 
> The "way it was" is to not care about them at all. There was no
> agreement on the the other thread if these things should be used or
> not. So I left it vague so everyone could use it, but they are not
> forced to.

Hmm, could this result in conflicting usage of these?

The "way it was" means the way the previous Portage team did it.

Being able to see IN_PROGRESS when it is in VCS on the tracker is
really handy, as that avoids skipping bugs; for those that deem that
mouse-over is unhandy, an alternative way is to see the open list is: 

https://bugs.gentoo.org/buglist.cgi?quicksearch=blocked%3A484436

> >> +There are a number of bugs named "[TRACKER] *" that collect bugs
> >> +for specific topics. Confirmed bugs should be marked as blocking
> >> +these tracker bugs if appropriate.
> > 
> > For clarity, it should be mentioned that this does not mean to block
> > the tracker for the next version; this could be misinterpreted.
> 
> Considering that the tracker gets renamed, I'm not sure what you mean
> here.

As you are confused yourself by misinterpreting what you have written,
you demonstrate the case for the need of clarity here; this is not
about the next version tracker or it being renamed at all, it's about
all other trackers that are not version trackers. The part of the
policy quoted here doesn't make that clear, it had me puzzling for a
moment too when I first read that; I think you were puzzled too now...

-- 
With kind regards,

Tom Wijsman (TomWij)
Gentoo Developer

E-mail address  : TomWij@gentoo.org
GPG Public Key  : 6D34E57D
GPG Fingerprint : C165 AF18 AB4C 400B C3D2  ABF0 95B2 1FCD 6D34 E57D

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

Re: [gentoo-portage-dev] [PATCH] Document bugzilla workflow

[Sebastian Luther]

Am 15.01.2014 17:20, schrieb Tom Wijsman:
> On Wed, 15 Jan 2014 07:29:19 +0100
> Sebastian Luther <SebastianLuther@gmx.de> wrote:
> 
>> Am 15.01.2014 04:11, schrieb Tom Wijsman:
>>
>>
>> I send the first mail with this wording 8 days ago. Enough time to
>> comment on it. I'd prefer to discuss it on the list.
> 
> Yes, but not all comments were discussed yet, therefore (dis)agreement
> on them is missing; and this last thing rather became a topic of
> discussion due to the work clashes that we saw happen twice.
> 
I'd say the clashes occurred because nobody mentioned at all what they
are working on. Since people started using IN_PROGRESS to mean "I'm
working on it", this shouldn't happen again.
> 
> Yes, I see some commit messages not refer to bugs which is something we
> will want to avoid; think this might need to go into the commit policy.
> 
There's nothing wrong with fixing/implementing something that nobody
filed a bug about.

>>
>> The "way it was" is to not care about them at all. There was no
>> agreement on the the other thread if these things should be used or
>> not. So I left it vague so everyone could use it, but they are not
>> forced to.
> 
> Hmm, could this result in conflicting usage of these?

Maybe, but I'd first see if the usage patterns converge to something
that makes everyone happy.
> 
>>>> +There are a number of bugs named "[TRACKER] *" that collect bugs
>>>> +for specific topics. Confirmed bugs should be marked as blocking
>>>> +these tracker bugs if appropriate.
>>>
>>> For clarity, it should be mentioned that this does not mean to block
>>> the tracker for the next version; this could be misinterpreted.
>>
>> Considering that the tracker gets renamed, I'm not sure what you mean
>> here.
> 
> As you are confused yourself by misinterpreting what you have written,
> you demonstrate the case for the need of clarity here; this is not
> about the next version tracker or it being renamed at all, it's about
> all other trackers that are not version trackers. The part of the
> policy quoted here doesn't make that clear, it had me puzzling for a
> moment too when I first read that; I think you were puzzled too now...
> 

Sorry, I failed to properly read what you quoted.

I think once you know that these other trackers exist, it's clear. If
you want something added there, that's fine with me too.


Sebastian

Re: [gentoo-portage-dev] [PATCH] Document bugzilla workflow

[Tom Wijsman]

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

On Wed, 15 Jan 2014 18:29:20 +0100
Sebastian Luther <SebastianLuther@gmx.de> wrote:

> Am 15.01.2014 17:20, schrieb Tom Wijsman:
> > On Wed, 15 Jan 2014 07:29:19 +0100
> > Sebastian Luther <SebastianLuther@gmx.de> wrote:
> > 
> >> Am 15.01.2014 04:11, schrieb Tom Wijsman:
> >>
> >>
> >> I send the first mail with this wording 8 days ago. Enough time to
> >> comment on it. I'd prefer to discuss it on the list.
> > 
> > Yes, but not all comments were discussed yet, therefore
> > (dis)agreement on them is missing; and this last thing rather
> > became a topic of discussion due to the work clashes that we saw
> > happen twice.
> > 
> I'd say the clashes occurred because nobody mentioned at all what they
> are working on. Since people started using IN_PROGRESS to mean "I'm
> working on it", this shouldn't happen again.

Neither should it happen again if bugs get self-assigned; the point
here is that neither of both is discussed, agreed on or documented
properly. Therefore the clashes need further revising of the workflow.

> > Yes, I see some commit messages not refer to bugs which is
> > something we will want to avoid; think this might need to go into
> > the commit policy.
> > 
> There's nothing wrong with fixing/implementing something that nobody
> filed a bug about.

Sorry, consider the common case where a bug was filed but the commit
message does not refer to that bug. Also note that I am trying to refer
to the ChangeLog of Portage itself, not that of the ebuild; thus I
mean the commit messages for the Portage repo, not to the Portage tree.

> >>
> >> The "way it was" is to not care about them at all. There was no
> >> agreement on the the other thread if these things should be used or
> >> not. So I left it vague so everyone could use it, but they are not
> >> forced to.
> > 
> > Hmm, could this result in conflicting usage of these?
> 
> Maybe, but I'd first see if the usage patterns converge to something
> that makes everyone happy.

The whole point of documenting it in a workflow is to make it converge;
if you instead leave things unclear or undocumented, you have no
guaranteed convergence and might even see a disconvergence.

It's already making people unhappy right now; because as it is
documented now, it is turned from the meaningful experience that the
previous Portage team had before to something that is meaningless. It
is a regression in checking the list of bugs that block the tracker, as
the states of the bugs no longer have a value as it is documented now.

If we change something about this, there should be a good reason to...

> >>>> +There are a number of bugs named "[TRACKER] *" that collect bugs
> >>>> +for specific topics. Confirmed bugs should be marked as blocking
> >>>> +these tracker bugs if appropriate.
> >>>
> >>> For clarity, it should be mentioned that this does not mean to
> >>> block the tracker for the next version; this could be
> >>> misinterpreted.
> >>
> >> Considering that the tracker gets renamed, I'm not sure what you
> >> mean here.
> > 
> > As you are confused yourself by misinterpreting what you have
> > written, you demonstrate the case for the need of clarity here;
> > this is not about the next version tracker or it being renamed at
> > all, it's about all other trackers that are not version trackers.
> > The part of the policy quoted here doesn't make that clear, it had
> > me puzzling for a moment too when I first read that; I think you
> > were puzzled too now...
> > 
> 
> Sorry, I failed to properly read what you quoted.
> 
> I think once you know that these other trackers exist, it's clear. If
> you want something added there, that's fine with me too.

We could add the sentence that I wrote earlier in the quote

    This does not mean to block the tracker for the next version.

but to avoid misreading we could write it up more positive and clear as

    These are other trackers than the next version tracker.

Optionally adding the redundant words "Note that" in front.

-- 
With kind regards,

Tom Wijsman (TomWij)
Gentoo Developer

E-mail address  : TomWij@gentoo.org
GPG Public Key  : 6D34E57D
GPG Fingerprint : C165 AF18 AB4C 400B C3D2  ABF0 95B2 1FCD 6D34 E57D

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

Re: [gentoo-portage-dev] [PATCH] Document bugzilla workflow

[Sebastian Luther]

Am 15.01.2014 19:41, schrieb Tom Wijsman:
>>> Yes, I see some commit messages not refer to bugs which is 
>>> something we will want to avoid; think this might need to go
>>> into the commit policy.
>>> 
>> There's nothing wrong with fixing/implementing something that
>> nobody filed a bug about.
> 
> Sorry, consider the common case where a bug was filed but the
> commit message does not refer to that bug. Also note that I am
> trying to refer to the ChangeLog of Portage itself, not that of the
> ebuild; thus I mean the commit messages for the Portage repo, not
> to the Portage tree.
> 
Not sure if we're talking about the same things.

1) If you fix something that has a bug, you should refer to that in
the git commit message.
2) There's nothing wrong with a git commit message that does not refer
to a bug, if there is no bug filed.

> The whole point of documenting it in a workflow is to make it
> converge;

Not the "converge" I meant.

What I meant was to allow people to test different styles and hope
that the one that works best will be adopted by everyone at some
point. Once that happens you can document that style.

> if you instead leave things unclear or undocumented, you have no 
> guaranteed convergence and might even see a disconvergence.

Yes, maybe. One then needs to see if that is a problem and if it is
then force everyone to use one style.

> 
> It's already making people unhappy right now; because as it is 
> documented now, it is turned from the meaningful experience that
> the previous Portage team had before to something that is
> meaningless. It is a regression in checking the list of bugs that
> block the tracker, as the states of the bugs no longer have a value
> as it is documented now.
> 
Previously the bug state was not used at all. There is no regression.

Re: [gentoo-portage-dev] [PATCH] Document bugzilla workflow

[Tom Wijsman]

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

On Wed, 15 Jan 2014 21:43:58 +0100
Sebastian Luther <SebastianLuther@gmx.de> wrote:

> 1) If you fix something that has a bug, you should refer to that in
> the git commit message.

Yes, this might need to go into the commit policy.

> What I meant was to allow people to test different styles and hope
> that the one that works best will be adopted by everyone at some
> point. Once that happens you can document that style.

Some styles only work properly if everyone uses the style; otherwise,
there's no point to doing the style because nobody else follows.
 
> Yes, maybe. One then needs to see if that is a problem and if it is
> then force everyone to use one style.

It is already raised as a problem in this thread.

> > It's already making people unhappy right now; because as it is 
> > documented now, it is turned from the meaningful experience that
> > the previous Portage team had before to something that is
> > meaningless. It is a regression in checking the list of bugs that
> > block the tracker, as the states of the bugs no longer have a value
> > as it is documented now.
> > 
> Previously the bug state was not used at all. There is no regression.

https://bugs.gentoo.org/show_bug.cgi?id=470992#c10
https://bugs.gentoo.org/show_bug.cgi?id=476738#c1
https://bugs.gentoo.org/show_bug.cgi?id=481366#c3
https://bugs.gentoo.org/show_bug.cgi?id=482650#c1
https://bugs.gentoo.org/show_bug.cgi?id=483628#c2
https://bugs.gentoo.org/show_bug.cgi?id=485226#c1

-- 
With kind regards,

Tom Wijsman (TomWij)
Gentoo Developer

E-mail address  : TomWij@gentoo.org
GPG Public Key  : 6D34E57D
GPG Fingerprint : C165 AF18 AB4C 400B C3D2  ABF0 95B2 1FCD 6D34 E57D

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