Make diagrams that explain the two-branch set up for PR processes
cansavvy opened this issue · comments
Background
#297 has made our PR process better, but also more complicated. #313 is adding a lot of information about our two-branch PR process in our CONTRIBUTING.md and it can be a lot to absorb and visualize in your head.
@jaclyn-taroni had the idea of making illustrations that describe this process so we can save our brain energy for elsewhere but so we can still leave the CONTRIBUTING.md doc with the idea of how PRs on this repository should work.
Problem
There's a lot of different branch names, github actions, and steps for our PR process now that we are implementing #297
We need a diagram to explain this so contributors don't have to spend a lot of time learning how this works.
What items should be incorporated into the diagram?
The diagram should explain/include
- The branches: staging, gh-pages-stages, master, gh-pages and what are they, what are their purposes, what do they matter to me?
- What's do the github actions robots do in between each step? When are things being triggered?
- What's happening with the Docker image at each step?
- What do the two scenarios describe for staging changes - > master look like (specifically about the cherry commits).
- How do master and staging relate throughout?
What are the recommended next steps?
- Let's take a look at other places on the web where they have these diagrams and they do it well for inspiration:
- Post a rough sketch of what this should look like here.
- Maybe make a prettier one using a graphic making app of some sort. Also post here.
- Finally add the diagram to CONTIRBUTING.md
I tried coloring by hand but it was too tricky. https://docs.google.com/presentation/d/1rbaXRYos1aP7u2cik7z7KTLMzX_ogU99gxsGWk22-gM/edit#slide=id.ga4c13fdd75_0_117
Couple quick thoughts: In the first one, there should be one middle track that represents the branch, not the PRs. In my mind, the PRs and merges are the curvy arrows (branch events too, but let's leave those aside); I might differentiate those somehow. (Both are ultimately merges, but one has a review step). So the hotfix branch would come off of master, get merged back into master by a PR, then get a merge from Staging and then PR back to staging. Something like this:
I was typing on my phone to say the same thing but then decided sketching a picture would be better ☝️ !
-
Try to make your curvy arrows always go downward? (think of the dots as being arranged in time, with the future down, so you can't take things back in time)
-
I think one thing that @jaclyn-taroni was looking for here was an explanation of when robots get triggered and what happens when they are. I think that may be best shown as separate from these exact diagrams: the details of finished and unfinished projects are not really important there, so you could show it with one "project" branch, staging, and master.
-
What are the grey arrows? Oh! those are the robots... But they don't show which robots may initiate changes and where... That should be in the diagram.
I think this has incorporated these comments? Let me know how you guys feel about these changes.
I do agree with @jashapiro that I don't think the robots part needs to be in the same diagram. (I think I brought this up in Slack as well.) As these stand, I find them to be a bit busy in a way that detracts from our goal.
Also consider: are all the details of what's going on with an finished vs. unfinished project getting merged on the left hand side necessary? If so, does it need to be in the same diagram as the merge to staging or can that diagram be broken up into pieces?
More general comment for both @cansavvy and @jashapiro - why would we need to merge something from staging into a hotfix branch?
More general comment for both @cansavvy and @jashapiro - why would we need to merge something from staging into a hotfix branch?
I think this is so the hotfix is added to the up to date version of staging and we don't accidentally save over changes when we use the master branch.
I've split up gha into its own thing and tried to simplify the other diagrams. How is this?
That makes sense re: hotfix, I suspect with the checks that's going to be a somewhat passive process.
That GHA diagram doesn't say when something runs. What is the action contingent upon?
That GHA diagram doesn't say when something runs. What is the action contingent upon?
The first sentence at the top: "Github actions initiated upon merges to master or staging" I can make it is own column if that's better, thought that might make it more complicated than needed.
But I guess docker-build is to PRs to master or staging so I can add a column.
