search

dwyl / contributing

:clipboard: Guidelines & Workflow for people contributing to our project(s) on GitHub. Please :star: to confirm you've read & understood! :white_check_mark:
88 stars 9 forks source link

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

Open nelsonic opened 6 years ago

nelsonic commented 6 years ago

Situation / Intro

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

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: dwyl-product-owner-guide-glossary-backlog

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

Sections to Include in the Revised Guide

The contents table should include:

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

tcm-workflow-with-blockers 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:

@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 commented 6 years ago

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

"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 commented 6 years ago

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

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

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

iteles commented 5 years ago

@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:

Other repos/parts of repos

@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: https://github.com/IQAndreas-testprojects/github-issues-import-example/issues/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 commented 5 years ago

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

iteles commented 5 years ago

:tada: image

nelsonic commented 5 years ago

@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 commented 5 years ago

@nelsonic I believe you were assigned to it because there was a question in https://github.com/dwyl/contributing/issues/109#issuecomment-443537333 directed at you and then it was just not reassigned back to me after that.

Happy with the assignment.

nelsonic commented 5 years ago

@iteles with regards to your comment above, https://github.com/dwyl/contributing/issues/109#issuecomment-443537333 ⏫ 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 commented 5 years ago

Link to https://github.com/dwyl/app/issues/238 Review this issue and project as part of rewrite.