EPIC: Consolidate our GitHub "Workflow" into *Single* Reference

[nelsonic]

Situation / Intro

At present we have six GitHub repositories that contain "bits" of our "Workflow":

• https://github.com/dwyl/contributing - General guidance on contributing to a GitHub project
• https://github.com/dwyl/definition-of-done - definition of "done"
• https://github.com/dwyl/process-handbook - internal "processes" for dwyl projects at the time of writing it's only got one image and is very text heavy ...
• https://github.com/dwyl/github-reference - GitHub for non-technical people ...
• https://github.com/dwyl/product-owner-guide - targeted at the Product Owner of the project
• https://github.com/dwyl/labels - explains the purpose of and use-case for each of the labels.

Additionally we have https://github.com/dwyl/dwylbot which attempts to "guide" people
to follow our "workflow" by posting helpful hint-messages in the issue(s) & pull requests.

Unfortunately, these repos are not congruent.

Furthermore they do not consider the use of GitHub Project Boards for visualising the progress of user stories through the "pipeline".
Allowing people to "drag-and-drop" issues from "Todo" to "In Progress" is much better UX than manually applying a Label and manually assigning the issue to themself ... the act of dragging the issue to "In Progress" column should trigger "WorkflowBot" to perform both of these "admin" actions (add label & assign to user).

Desirable

It would be preferable to have a single repository that defines our complete GitHub Workflow.

Note: I'm not suggesting that the product-owner-guide is not useful (in fact I think that it's really good!) just that it's not tightly associated with the GH Workflow e.g:

I suggest we re-name the https://github.com/dwyl/contributing to "github-standard-workflow" (because including the word "standard" means that nobody can "argue" with it ... https://github.com/standard/standard ...) 🙄
And then merge all the other individual repositories into the newly renamed one as .md files within it.
We could even craft it into a "GitBook" the way "ThouhtBot" did with: https://thoughtbot.com/playbook

Todo

• Collect feedback from existing "users" of the dwyl GitHub Workflow (team members & clients)
  • Revise our existing GitHub Workflow in response to feedback.
• Use GitHub Project Boards (trello-like drag-and-drop) so that everyone on the project can see at a glance what stories/tasks (issues) are being worked on and by who. (there's a reason why Trello is so popular and tools like "ZenHub" and "Waffle.io" exist ... people want a visual "Board")
• Determine which other columns we would like to Add to the standard GitHub Project Board (the default columns are Todo, In Progress and Done) > can we open a separate issue for this?
  • "WorkflowBot" should automatically create the full array of Project Board columns when the app is added to the project using the API: https://developer.github.com/v3/projects/columns

Sections to Include in the Revised Guide

The contents table should include:

• Contributors - link to a revised CONTRIBUTING.md that is simplified for Open Source.
  • Separate guide
    and detailed for "client work".
• Stakeholders - anyone who has a vested interest in the success of the project but who may not be involved in delivering the work.
• Product Owner Guide - we can link to the (revised) product-owner-guide

Pain Point

Given that we don't have a single place we can point people to,
I spent a chunk of time attempting to summarise the "Workflow"
for one of our clients in a "single page" diagram:

---

Workflow Diagram

Click image to view large version!
Edit this Google Doc: https://goo.gl/2UNVbw (using draw.io)

This workflow is optimised for our biggest constraint: UI Developer Time.

Please Note: I am not for a moment suggesting this diagram is "perfect"! in fact I think it's "meh".
But it's just to illustrate that I had to create several new columns in addition to the default ones that come with GitHub Project Boards and then explain (visually) what each one is for.

Questions:

• Should we use GitHub Project Boards for our Open Source modules? or should we limit the use of the boards to the actual Projects? How much "structure" do Open Source modules need in their workflow? (how much is "too much" which results in putting people *off contributing...?)
• Should "WorkflowBot" be applicable to all types of GitHub Repos or just "Apps" worked on by teams of (paid) developers.

@Cleop / @iteles this is what I mentioned this morning in our verbal discussion.
I've attempted to capture as much as possible in this issue to ensure that we cover everything in the "Epic".

[nelsonic]

Not having a well-defined workflow is costing us time (money)
as people "don't know what to work on next"
or work on low-priority (low-benefit to end-users) issues
and don't clearly communicate with the rest of the team
(e.g: by "dragging* the story into the In Progress column ...
multiple people work on the same story wastes everyones time!)

Also, people still insist on discussing user-stories in ephemeral or verbal "chat",
so issues do not contain the full "context" or discussion. This destroys remote-teamwork.
People rarely use checklists, the best way to track your own progress (and communicate with others)
and nobody in dwyl has adapted to using GitHub Project Boards (Automated Kanban) ...

"Stakeholders" love Trello. (which is why Atlassian paid $425 million for it last year ...)
GitHub Projects gives us many of the features of Trello for free!
Specifically the ability to see "at-a-glance" what is being worked on (by who)
and how "complete" it is ... if people use checklists ... 🙄

[nelsonic]

No product owner or QA/lead wants to see a branch called "quick fix" ...

Instead, they want to see a descriptive name and an issue number e.g:

"quick fix" is exactly what its' name suggests, not a long-term solution to the problem with maintainable code, documentation and tests. 😞

[iteles]

@nelsonic Thank you for opening this issue. I've been paying much closer attention to how/if these repos are used in the last few months since it was opened.

I very much agree that this needs a serious revision and that our entire workflow needs to be in one place.

The thing to consider here is that there are various types of workflow included in these 6 repos.

One resource: github-standard-workflow

This is by far a better name. 💪

Our Contributing Guide (extremely useful as a 'stand-alone' to add to our contributing.md files across OSS repos), Definition of done, definitions within 'labels' and everything in the main readme of the 'Process Handbook' absolutely all belong in the same repo.

Within github-standard-workflow, I propose the following next steps:

• Our Contributing Guide remains as the _main readme so that it is still the first thing contributors to our OSS projects/packages/modules see
• Introduction is updated to reflect this
• Table of contents is added for remainder of documentation (definition of done, labels and scrum/development project processes)
• All other readmes are added in a relevant folder structure within the repo for orderly access

Other repos/parts of repos

• Within 'Process Handbook', there are a lot of 'how to run a company' md files - these should be moved to the hq repo
• The code for labels should remain in the labels repo so that it can keep being evolved, with a reference to github-standard-flow for the label definitions
• Open questions:
  • https://github.com/dwyl/product-owner-guide - I had originally envisioned this as a resource far beyond GitHub, as a reference for product owners in not just the technical/Github realm of their roles but also in being POs in general
    • As you say, it's hugely out of date, not tied tightly enough to our own processes and needs a firm revision
    • The vast majority of what is there now is Github-flow specific so I don't see why it shouldn't be moved into github-standard-workflow and then if we choose to evolve it beyond that, we can break it out into its own repo again
  • https://github.com/dwyl/github-reference - This is an elementary Github resource which we found necessary when we first started working with clients (as a precursor of the basics before launching into the PO guide), but could very well be useful to beginner developers too
    • I suggest we a) Check to see whether there are any existing resources that are doing a better job of this for non-technical people and b) if not, update this issue and add it to github-standard-workflow

@nelsonic Do you disagree with either of the first two points in the list above?

If not, I'll move forward and get this done.

On merging repos

There is really no way to port issues and their history from one repo to another. The only solution right now seems to be: https://github.com/IQAndreas/github-issues-import which creates threads posted by a bot like this:
IQAndreas-testprojects/github-issues-import-example#10

The vast majority of the issues on https://github.com/dwyl/process-handbook are opened by myself and @rub1e so this isn't too much of an issue as we can use it as a backlog grooming session and re-open relevant issues only. https://github.com/dwyl/labels has quite a lot of issues opened by others however. We can keep these here if we decide to keep the code for labels separate to the labels definitions as proposed above.

---

Lastly, the priority-1 update for me here is to include our usage of Github Projects and getting dwylbot to automate labels for us. We've been discussing it for a while and I feel it every day when I'm the one updating labels because having to update the same thing in two places means no one does it.

[nelsonic]

@iteles issue transferred. Want to transfer any issue from one GitHub Repo to another, sign up for "beta".

[iteles]

🎉

[nelsonic]

@iteles why am I the only one that is assigned to this issue?
If nobody else is interested in solving this problem, I'm happy to solve it "top-down".
But my reasoning for opening it was to get everyone's feedback. 🤔

[iteles]

@nelsonic I believe you were assigned to it because there was a question in #109 (comment) directed at you and then it was just not reassigned back to me after that.

Happy with the assignment.

[nelsonic]

@iteles with regards to your comment above, #109 (comment) ⏫
I do not disagree with either of the first two points (or any of other the points)

I don't think we need to merge the repos (yet).
If we simply consolidate them into /github-standard-workflow
(the renamed /contributing ...)
We can then simply link to the revised/updated workflow whenever needed.
If anyone mentions being "confused" by having too many similar repos, we can simply replace the README.md in that repo with a "GOTO" link.

[iteles]

Link to dwyl/app#238
Review this issue and project as part of rewrite.