A case for GitHub Projects

[philschatz]

This issue contains items that point at manual bookkeeping (error-prone) we do in our current system and how they can be solved using GitHub Projects for Organizations. (All of the screencaps are working code that you can try today!)

(vote on this idea below)

Accurate Sprint Progress

Currently, there are several places where manual effort causes things to be missed. Automation can help us with these. For example, development work is done in GitHub while PM status is in multiple Trello Boards and time/effort recording is in TrackingTime. This leads to multiple different places that need to be manually kept in-sync. An example story would be:

Click me to expand the story (it's a lot of steps)

1. An issue is discussed and discovered in slack 1. A person finds the right board on Trello and copies an existing template to create a Card 1. A PM adds the correct labels and associates the card with a Key Deliverable somehow (maybe an additional label) 1. The dev ("dev1") opens Trello and finds the Card to work on 1. The dev adds a time estimate to the Trello Card 1. The dev begins working on the Card 1. The dev submits a PullRequest to fix the Issue 1. The dev opens Trello and finds the Card 1. The dev updates the time on the Card 1. The dev moves the Card to the "Needs Testing" column 1. Another developer ("dev 2") opens Trello and finds the board 1. Dev2 finds the Card 1. Dev2 clicks the Pull Request 1. Dev2 reviews the code 1. Dev2 re-opens Trello, finds the card, and updates their time 1. Dev2 moves the Card to the Testing column 1. QA repeats a similarly-complicated process that dev does, but it includes deploying the code for testing

Automatically Add and Move Cards

Currently:

• we require people to switch systems in order to add new work.
• we require people to update the cards and remember to move them and notify people.

With Projects, the cards can move automatically when any of the following occur:

• The state of an Issue/PullRequest changes (opened/closed/merged/reopened)
• The labels on an Issue/PullRequest change
• An Issue is (un)assigned to a user
• A PullRequest Review is added/accepted/rejected
• A comment is added to an Issue/PullRequest

You can see an example of this by checking out these Projects that, with zero effort, already move Cards around automatically as Issues/PullRequests are updated:

• All Openstax Repos
• All Connexions Repos
• Books Repo

Note: The moving logic can be configured differently for each board the Issue/PullRequest is in.

Quickly Create a Card (with context)

Currently, discussion frequently happens in Slack and then a Card is created.

With Projects, anyone can convert a Slack discussion into a card by just adding a :github: reaction (or 🌲 ). A Card is automatically created on the appropriate Project with a link to the Slack discussion. This card can then be easily moved but it is not lost.

Accurate KeyDeliverable Progress

Currently, a Card can only be on one board. This makes it difficult to know the status of larger concepts like KeyDeliverables, resorting to labeling.

With Projects, cards can be on Multiple Boards.

No app needed, just webpage links

Automated reporting and burnup charts

As people update/move cards, the charts update. No waiting, or running scripts.

Why spend $$$k for 3rd party?

... when we can spend that money internally to have a tool that works for us.

Disadvantages

• labels can be inconsistent across repositories (a bot can fix this)
• cards cannot be commented on until you convert them to an Issue (which lives in a repository)
• Issues cannot move between repositories (but can move between Projects). See #33 for a way to accomplish this.

Vote!

What do you think? (click a bar to vote)

[philschatz]

Example of boards and how the columns could be automatically configured

Listed below are some boards and examples of columns that could be mostly automated using the Automatically Add and Move Cards section described above. Note the a person can always move items on the board manually.

CNX Sprint

Trello Column	How Cards/Issues/PullRequests can automatically move into it
Backlog	New Issue (or it goes into another board)
Needs Clarification
On Deck	assigned to a user? (was not assigned before)
Doing Needs Code	New PR (or reopened PR), all reviews done but not merged, has WIP in the title
Waiting for Code Review	has a Reviewer assigned
Need Test Plan	PR reviews are Accepted (or PR is merged)
Needs Deployment to QA/Staging
In Sprint Testing
Regression Testing
Ready to be Released
Done/Already Released
Will Not Be Released	PR is closed, Issue has wontfix label (and is closed)

Tutor Sprint

Trello Column	How Cards/Issues/PullRequests can automatically move into it
1A: Backlog Define Design Decomp	New Issue (or it goes into another board)
1B: a15k Backlog
2A: DEFINE, DESIGN, DECOMPOSE
2B: UX Design
3A: Backlog Code
3B: CODE & PEER REVIEW	New PR (or reopened PR)
4: UX REVIEW	PR reviews are Accepted (or PR is merged)
5A: Functional Verification	Issue is assigned
5B: Verified on QA	Add verified label
5C: In Regression
5D: Ready To Be Deployed
Release 8.02.15-1
Done: Assessment Network
Done: Will Not Release	PR is closed, Issue has wontfix label (and is closed)

Books Sprint

Trello Column	How Cards/Issues/PullRequests can automatically move into it
Inbox for Prioritization	New Issue
Non-10K Backlog
Winter 10K Backlog
Coding	New PR (or reopened PR)
Editorial
Production
QA	PR reviews are Accepted (or PR is merged)
Done	Issue is closed	PR is closed

BIT Sprint

Trello Column	How Cards/Issues/PullRequests can automatically move into it
Backlog Define/Design/Decomp	New Issue
Backlog UX Design
Define/Design/Decomp
Backlog Develop
Doing	New PR (or reopened PR)
Dev Verify	PR has a requested reviewer	WIP title is removed
UX Review	Requested review from Fred
5A: Functional Verification	PR reviews are Accepted (or PR is merged)
5B: Verified on QA
5C: In Regression
5D: Ready To Be Deployed
Release 8.02.15-1
Done Not Released	Issue is closed	PR is closed

Click me to see what the configuration for each Board would look like

```yaml # The format of these are: # # Column Name ({column_index_or_id}): # - {state_change_which_causes_the_move_to_this_column} # cnx_sprint: Backlog (1): - new.issue On Deck (2): - assigned Needs Code (3): - new.pullrequest - reopened Waiting for Code Review (4): - added_reviewer Needs Test Plan (5): - accepted - merged Will not be Released (6): - closed.pullrequest - added_label(wontfix) tutor_sprint: "1A: Backlog Define Design Decomp (1)": - new.issue "3B: CODE & PEER REVIEW (6)": - new.pullrequest - reopened.pullrequest "4: UX REVIEW (7)": - accepted - merged "5A: Functional Verification (8)": - assigned "5B: Verified on QA (9)": - added_label(verified) "Done: Will Not Release (14)": - closed.pullrequest - added_label(wontfix) books_sprint: Inbox for Prioritization (1): - new.issue Coding (4): - new.pullrequest QA (7): - accepted - merged Done (8): - closed.issue bit_sprint: Backlog Define/Design/Decomp (1): - new.issue Doing (5): - new.pullrequest - reopened.pullrequest Dev Verify (6): - added_reviewer UX Review (7): - added_reviewer(@Fredasaurus) "5A: Functional Verification (8)": - accepted - merged Done Not Released (13): - closed.issue ```

[philschatz]

How it relates to Features Requested by people

AKA How these issues can be solved today using GitHub Projects

The 1st-level list describes the category of features that others have expressed as important, and the 2nd-level list describes how GitHub Projects can address those feature requests

• Automate : Integration with other parts of workflow (TrackingTime, PullRequests, Emails)
  • Anything you do on GitHub can move a Card: labels, assignees, reviewers, merge, close, special comments. See https://github.com/philschatz/project-bot#rules
• Data : Extracting and using the PM data
  • Every event is reported. Can implement push or pull notifications
• Dogfood : Testing the PM tools, using the PM tool for Knowledge Base articles, org-wide adoption, common inbox
  • Devs & QA already use GitHub
• Entry : Ease of entering Cards including custom fields
  • 4 ways to create a card:
    1. Click + on a column on the Board
    2. Create a new Issue in a Repository
    3. Create a new PR in a Repository
    4. React to a Slack message with the :github: emoji (only enabled for the #cnx channel for now)
• Estimation : Entering Estimates and reporting on those estimates
  • Specially formatted titles or labels
• Glance : Things to see at-a-glance (specific to a Team/Person)
  • Cards can be in multiple Boards, can have a Project for each Team
  • Can have an "All Openstax" Board so people can filter on themselves to see a personalized list of TODO, and DID
  • Due dates can be milestones
• Links : Seeing links to other Cards or artifacts
  • Bi-directional links are automatically created
• List : Support for checklists or TODO items
  • Markdown supports checklists, ordered lists, unordered lists
• Notify : letting others know something changed
  • @mention individuals or Teams, Assigning/Reviewing/Commenting are all emailed... Can [Unsubscribe] if no longer participating
• Org-view : Viewing the whole organization at a glance
  • Cards can be in multiple boards. Can have a Project for each KD, Projects can be Cards in other Projects (to quickly show progress bars)
• Reporting : (auto)Creating/Viewing Reports
  • Burn-Ups and other charts can be built based off of the data
• Status : Important things to see on the card (without opening an individual card)
  • Labels, merge status, assignees are visible. "Stale" can be an auto-added label or a column. Priority can be a label

Other issues that may arise:

• You can move an Issue if it was created in the wrong repository. See https://github.com/openstax/staxly#move-an-issue-to-another-repository-34
• Batch editing Cards: Not implemented yet, but See https://github.com/openstax/staxly/issues/48

GitHub

philschatz/project-bot

project-bot - Automatically add and move Issues/Pull Requests on a Project board

GitHub

openstax/staxly

staxly - :robot: beep boop