Document development process

[seanlinsley]

Today in IRC we've been discussing Waffle.io and Huboard as options to help visualize and track progress, and eventually decided we'd give Huboard a try: https://huboard.com/gittip/www.gittip.com 🍻

Now we need to document the process so the custom way we use it is clear to newcomers.

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[seanlinsley]

Taking this unless someone else wants to do this 🐱

[chadwhitacre]

@seanlinsley I may ask you for it if ever I finish #1699.

[seanlinsley]

You already gave a good whack at this over in badges/shields#86 :

I've set up four workflow stages: Backlog, Ready, Work in Progress, and Review. These manifest as four labels in GitHub.

I propose that we adopt the following practices:

• Everyone is responsible for assigning their own tickets to themselves and moving their tickets through the workflow.
• Everyone gets 3 tickets under Ready, 1 under WIP, and 1 under Review.
• When your WIP is ready for review, move it to Review and unassign yourself.
• Someone else has to review and merge your code. You can't merge your own code. You can merge anyone else's code.
• If you notice a PR awaiting review, assign yourself to it. If you need to send it back for more work, move it to WIP and assign it to the original author.

Remember that kanban is pull-based. To the right of "Review" is Heroku, and it is constantly pulling, gently tugging, as if to say, "Please, give me more code to deploy!" What this means is that PRs ready for review should take precedent over WIP.

[chadwhitacre]

Yeah, though there's no Stalled state there. Between that and IRC we have plenty of verbiage to draw from. Need to make the page! And nav sux. :-(

[zwn]

I still think that a general "Ready to be work on" label would help a great deal. Can we please not mix "what I want to work on next" with "this can be worked on because the discussion is over and the solution is clear"? I'd propose to use assignment as "intent to work" and label "Ready to Start" as a general "anyone can work on this, the discussion is over". I'd like to prevent #831 (comment).

[seanlinsley]

@zwn you can't really prevent new people from asking for permission. Many new contributors are going to ask first because they don't want to step on anyone's toes and also want to confirm that the given ticket is worth working on.

That's not to say there isn't merit in the idea of having the two labels you described.

[zwn]

@seanlinsley What I'd like to prevent is the confusion - someone labeling issue as "Ready to Start" and then @whit537 coming along saying that since no one is assigned to the issue the label should not be there. I propose to have a generic label "Ready to Start" without assignments that notifies possible contributors on what they could work on.

[seanlinsley]

This is a hard problem, and I'm not sure we'd be effective trying to maintain a label (I assume a Huboard label?) of this scale. Ostensibly, something like 200 of our 400 tickets are ready to be worked on. Maybe it would be better to have a "requires discussion" label, blacklisting instead of whitelisting?

[zwn]

I almost feel that most issues we have are not ready to be worked on but require more discussion (that cannot be done by a newbie, a decision is required). So I was also aiming for less work 😄 I think that having let's say 10 to 20 tickets marked as ready to work on could encourage new developers to join in. It would have helped me to start. Having blacklisting label would not help that. It is also related to the discussion we had on Saturday that maybe, just maybe, the way to go forward is not to say that everyone should just scratch their own itch but to have a better sense of direction. Maybe the 3 start label supports that as well. Ok, I'll shut up now and go to work 😉

[seanlinsley]

I don't know; personally I just don't want one more thing to maintain. I think a better solution is to guide new contributors. If someone asks for something to work on, find something for them! It only requires a couple minutes, and it seems like that added human interaction is valuable.

[galuszkak]

@zwn my questions on 831 are more because I'm new here on gittip and only done some pull requests. I want to help more gittip team, but I just would love to get reviews and be guided as I'm more Django/Python developer and first time working with Aspen. If something is really easy I just ask can I work on this. Just want to make impact on things that matter for user experience and make project better.

[galuszkak]

@seanlinsley exactly I really value human interaction because I can learn how people see some things and learn how they feel this project. This is really important for me.

[chadwhitacre]

I think we need to support several scenarios:

1. A newcomer wants to browse issues to find something to work on.
2. A newcomer wants to chat with an existing team member to find something to work on.
3. A newcomer has specific itch to scratch.

For (3) they probably give us a PR as the first thing we hear from them (e.g., #1437, #1558). For (2) we point them to IRC (yes, @galuszkak?). For (1) I like @zwn's idea of pointing people to the unassigned tickets under "Ready to Start" on Huboard. We should keep ten or twenty tickets there that are good first tickets. Any of us can also fix them as well, but we should make sure to keep that pool adequately filled via our priority parties and one-off prioritizations.

[seanlinsley]

My concern is having to maintain two separate 'ready to start' labels; one for newcomers (that we will otherwise work on), the other for actual planning by the core dev team. Is the first one really going to be kept up to date?

[chadwhitacre]

I'm not seeing the 'ready to start' labels as separate. We use 'ready to start' with or without assignment in what I think is a natural way: assigned means, "this is my personal queue of things I hope to get to," and unassigned means "this is stuff the group as a whole thinks a newcomer could start with."

We actually have a separate ticket for a doc about the prioritization process: #1192. With my "developer" hat on, and especially as a newbie, I don't need to worry about how priorities got set, just that they are set. Let's use this ticket to discuss how we're telling developers to decide what to work on next. What's the algorithm a developer should apply when sitting down to hack on Gittip and deciding what to work on?

[zwn]

I've created a 'DevX ★' label for super annoying developer issue things that should be fixed asap.

[chadwhitacre]

@zwn Sounds good. Gives us a way to call out important DevX issues without the complication of a full three-star system.

[seanlinsley]

The lack of this documentation bit us as @clone1018 and @galuszkak have been independently working on #998 (IRC)

[chadwhitacre]

I wrote a doc about GitHub labels:

http://building.gittip.com/policies/label-github-issues

It doesn't address the full process as asked for here, but the ticket we had for just doc'ing labels (#1193) was closed in favor of #1192 which was closed in favor of this one. :-)

[chadwhitacre]

We're no longer using Waffle or Huboard.