Working with branches documentation

[allyhawkins]

Which issue does this address?

Closes #14
Stacked on #171

Briefly describe the scope of the added docs file, including whether you link out to any external docs.

Here I'm adding the doc for working with branches in Git, including instructions on how to create a branch using Gitkraken. The first section is an intro into what a branch is and a note that before making changes you should make a feature branch. I chose to give some context into the purpose of the feature branch here, explaining that after creating one, changes can be committed and then you can file a PR to incorporate your changes. I also included a link to GitHub docs on branches.

The next section is a step by step on how to actually create a branch in GitKraken with screenshots. Maybe this is overkill, because I also included a link to the GitKraken page that includes step by step instructions and a video.
Do we want a link to command line instructions?

Will you need additional visual aids for these docs?

I added in screenshots for creating a branch.

Any other comments for reviewers?

Generally, I was unsure about the level of detail here and if I covered everything I was supposed to so please let me know if something is missing!

Another question I have is around branch naming, do we have a recommended convention? I just used our convention that we use internally, but if we don't want to recommend anything I can remove that.

Author checklist

• The docs page has been added to the nav section in mkdocs.yml
• The docs adhere to the style guide structure directions?
• The docs adhere to the style guide language directions?
• The docs adhere to the style guide tone directions?

Reviewer checklist

Please refer to the docs style guide while reviewing this pull request.

• Do the docs adhere to the style guide structure directions?
• Do the docs adhere to the style guide language directions?
• Do the docs adhere to the style guide tone directions?

[sjspielman]

I think this page would benefit from a little more organization to make it easier to scan, since this will be a new concept for a lot of contributors. I'm envisioning sections overall this, where each section can have 2-3 sentences or bullets (definitely use more bullets!). A lot of this content is already there but could be reorganized a bit.

Also, remember to use present tense.

# Working with branches

## What is a branch?

- definition
- why we like to use them
- include here both the link to git and gitkraken docs on branches (not sure if it has to be a callout though? let's see!)

### What is a feature branch?

- definition
- for openscpca, we want you to make this off of main every time

### When should you use a feature branch?

- note here that each branch is 1 PR, it's not one branch for your entire time as a contributor. 

### Overview of working with branches

this can be the little overview you have right before "creating a feature branch," but bulletified

## Creating a feature branch in GitKraken  <- your current section "creating a feature branch"

[sjspielman]

We're going to get a lot of branches called "add-new-analysis" here if we do this!
How about a specific example? Like..

For example, if you are writing an analysis to add cell type annotations to Ewing's sarcoma samples, you might name your branch username/celltype-ewings.

Maybe also a callout box with protips:

• You can also indicate the issue number in your branch name like username/42-celltype-ewings.
• no spaces or special symbols besides - and _
• your branch names should always be unique; you can run into trouble reusing branch names

[sjspielman]

also using allyhawkins is fine too I think, as long as you're ok proclaiming you're the author of these docs ;)

note also the screenshot might have to change too for a more descriptive branch name

[sjspielman]

As per my overall review comment, I'd delete this and keep all links at the top so they can find external resources all in one place

[sjspielman]

I'd rearrange:

When you are working on your own analyses or proposing a change to the main code base, create a feature branch with an informative name from the `main` branch of your fork.
  - Haven't forked yet? Please see these [docs for forking](stub)

[sjspielman]

present tense and shorter, eg

"Write code in your feature branch (see making commits)"

[sjspielman]

Once your analysis or changes are complete

let's not say this - we don't want them to think the whole analysis is one branch/PR!

[allyhawkins]

@sjspielman thanks for the suggestions! I believe I incorporated your organization tips and addressed all your comments, but let me know if I missed anything!

[sjspielman]

I left a lot of comments but don't let that scare you, it does look good! Most of my comments are to make sentences shorter and/or more spaced out.

I have a couple "real" comments:

• Do we need to instruct them to actually checkout main first?
• Let's make sure we point out the need to be in sync with upstream.
• We should reduce some of the ambiguity in the figures, since stuff is shown both in the local menu and the git graph. Arrows might help?

[sjspielman]

you can delete this if you want

[sjspielman]

Suggested change

	2.Create and checkout a new branch by right-clicking on the `main` branch and selecting `Create branch here`.
	2. Create and checkout a new branch by right-clicking on the `main` branch and selecting `Create branch here`.

[sjspielman]

Let's get a little more specific - you can either do this in the local menu, or in the graph. Which do we recommend? Would an arrow help?

[allyhawkins]

Do we need to instruct them to actually checkout main first?

Yes? I think we keep this step. Even if they can just right click on main, I think it's the easiest way to make sure your up to date is to checkout main and then create a branch.

We should reduce some of the ambiguity in the figures, since stuff is shown both in the local menu and the git graph. Arrows might help?

I added some wording to show both options of double-clicking or using the menu. Personally, I never use the menu and always use the branch graph, but I know some people like the menu. I think it's also helpful to show what the screen looks like when something happens in both places.

I still have a question about the pushing part. So once we clarify that then this should be ready for another look.

[jashapiro]

I just had a couple of high level comments/questions that I wanted to get in here.

[jashapiro]

I think we might want to make this the first section? If people are familiar with Git, they might want this information first. If they are not, we can direct them to keep reading.

[sjspielman]

I'm not sure about this - I think for advanced users I'd rather they just scroll a little (this is one reason to keep nested headers above, makes this section a little more obvious I think), but for beginners it would be overwhelming to see this list before having the "what are branches and why" context. Basically I'm less concerned with advanced contributors vs beginners, and I think it's best to structure docs based around beginners' needs.

[jashapiro]

Part of my reasoning is that this also is the why for this whole page. I would make this header first, and add "We use branches in OpenScPCA because..." before the bulleted list.

[allyhawkins]

Moving this section entirely broke the flow to me and I wasn't a fan. So I came up with a compromise and included a brief "why do we use branches in OpenScPCA" as the intro before any of the sections. Then you can read on for more details. You can see this update in b893f67.

[sjspielman]

LGTM! Unless you want me to weigh in on any further conversation about organization, I don't need to see again, and note I do like the current overall structure - open with general information and then nail down specifics as the docs proceed (not quite the same as this style guide recommendation, but similar vibes! https://github.com/AlexsLemonade/OpenScPCA-analysis/blob/main/docs/general-style-guide.md#organizing-the-information)

[sjspielman]

I'm not sure about this - I think for advanced users I'd rather they just scroll a little (this is one reason to keep nested headers above, makes this section a little more obvious I think), but for beginners it would be overwhelming to see this list before having the "what are branches and why" context. Basically I'm less concerned with advanced contributors vs beginners, and I think it's best to structure docs based around beginners' needs.

[allyhawkins]

As noted in #181 (comment), I made a slight change to the intro of this section. I also updated the steps to include a link to making sure you have set your upstream repository, made syncing your main with ALSF main optional, and adjusted the screenshots for branching off ALSF main.

Going to re-request a look from @sjspielman

[sjspielman]

Mostly we need to fix the numbers in rendering - too many 2.. Happy fighting with spacing!

[sjspielman]

space!

Suggested change

	3.You will then be prompted to name your branch.
	3. You will then be prompted to name your branch.

[allyhawkins]

Just noting that the only way that I've gotten the numbering to work correctly is to actually not use any spaces. It should be correct now and I double checked on the build.

[sjspielman]

can we actually make this arrow thicker? It's very small compared to the rest of the image