Update release workflow to reflect use of 'version' branches

[bourque]

Change Summary

Overview

This PR updates the release workflow documentation to reflect our new workflow -- one that doesn't use a main branch but instead uses 'version' branches (e.g. v0.1.x).

New Files

• docs/source/_static/git-workflow.png
  • A diagram that I created to reflect this workflow. I couldn't find anything like it online, so I just created something with a draw tool. This replaces the diagram that was previously used in git-and-github-workflow.rst

Updated Files

• docs/source/development/release-workflow.rst
  • Updated description of the release workflow
• docs/source/development/style-guide/git-and-github-workflow.rst
  • Updated workflow diagram

Testing

For reviewers, it would be good to know if this workflow makes sense as i've described it? What needs to be tweaked?

[maxinelasp]

LGTM, thanks for updating this!

[bourque]

Thanks @maxinelasp!

@greglucas Since you introduced the concept of the version branches, it would be good to get your opinion here and make sure I got this down right, if you have time!

[greglucas]

I find these diagrams confusing to follow unless you already sort of know what you're doing. I've tried explaining them to people new to git before and it was just blank stares. So, I guess I'd recommend just linking out to someone else's so we don't have to maintain/explain it? I think the Atlassian gitflow diagram you had before is awfully close to our process, we just aren't using the "master" branch anymore and keeping the "release" branch only. So sort of just reducing one of the steps.

I am fine with this new diagram as well, but it'd be nice if you could put it through an image shrinker as well so it isn't 161KB.

[bourque]

I find these diagrams confusing to follow unless you already sort of know what you're doing. I've tried explaining them to people new to git before and it was just blank stares. So, I guess I'd recommend just linking out to someone else's so we don't have to maintain/explain it? I think the Atlassian gitflow diagram you had before is awfully close to our process, we just aren't using the "master" branch anymore and keeping the "release" branch only. So sort of just reducing one of the steps.

I am fine with this new diagram as well, but it'd be nice if you could put it through an image shrinker as well so it isn't 161KB.

Thanks for the feedback Greg. I'm hesitant to switch out the diagram in favor of Atlassian's, because this new diagram is (accurately, I think) reflecting our actual workflow (and I designed it to look as similar to Atlassian's diagram as possible). I agree that this stuff is inherently confusing and hard to learn, but I'm not sure that showing Atlassian's diagram and then saying "well actually this part is different" would be less confusing. And I don't agree that our new method is close enough to the Atlassian release-driven workflow, because we are not just using a release branch instead of a master branch -- we are keeping every release branch, and a new release branch needs to be created when certain conditions are met.

Would it suffice to keep this diagram and then add a note somewhere along the lines of "for more information about release-driven workflows see [this Atlassian page]"?

Good catch on the file size, I can definitely make that smaller!

[greglucas]

@bourque , I should have pinged you yesterday I only thumbs-upped your message which probably didn't notify you, sorry for that.

Would it suffice to keep this diagram and then add a note somewhere along the lines of "for more information about release-driven workflows see [this Atlassian page]"?

I think that would be fine, but I am also totally fine with what you wrote and keeping it like this. So, this is good with me once you shrink the image down.

[laspsandoval]

Nicely done.