Navigating branches and syncing

[mzayeddfe]

I added instructions for:

• Recording changes
• Syncing with the remote
• Switching branches

For each of them, i added instructions for gitbash, R and Pycharm.

Things I'd appreciate feedback on in particular:

• if I should put instructions about pulling changes in syncing to the remote as well or leave it where it is
• i added steps for making changes in the recording changes qmd based on a discussion i had with lauren. is that ok?
• i added instructions for git status but can remove if ott. same for adding origin "branch name" after push and pull. if you prefer for me to change it to just git push and git pull, i'm happy to change it.
• are the red rectangles/squares in the images not helpful or helpful?
• The branch name i used in the pycharm screenshots has R in it. is that ok?

[rmbielby]

I've got half way through reviewing and need to switch on to something else, so thought I'd just send you what I've done so far.

Some broad level comments are:

• I think the use of h3s throughout is a bit overkill and is starting to feel a bit forced (like just repeating the first sentence that follows it in some places). Feel like it'd be simpler if we ditched most of the h3s. If a page is getting so long that it feels like it needs a h3, then maybe that page just needs splitting into multiple pages.
• I'd like to make sure we've got some sort of text for all images. I've got it as caption text at the moment, but might be that the ideal is if we can figure out how to make it proper alt-text, so that it's hidden but gets read by screen readers. If that's awkward to do, then go with caption text.

On your questions:

if I should put instructions about pulling changes in syncing to the remote as well or leave it where it is

• I've adapted the sandbox now so that there is a pull section, but it comes after a bit of an intro to GitHub, so can be left until that's been written in another branch

i added steps for making changes in the recording changes qmd based on a discussion i had with lauren. is that ok?

• Yep, think that makes sense, just the comment to make it into a callout box

i added instructions for git status but can remove if ott. same for adding origin "branch name" after push and pull. if you prefer for me to change it to just git push and git pull, i'm happy to change it.

• I think it's useful referencing git status. I'd be tempted to change the git push ... to be git push --set-upstream <github_id>_main, but highlight that you only need to set the upstream on the first push, after that you can just use git push.

are the red rectangles/squares in the images not helpful or helpful?

• Helpful I'd say

The branch name i used in the pycharm screenshots has R in it. is that ok?

• in the sandbox, I've just removed references to specific software in the branch names now. Might be worth just redoing the images quickly to match

[Lsnaathorst1]

As we found together, this needs to be 'git push --set-upstream origin _main'

[rmbielby]

A few more ideas for this one. Sorry if this feels like shifting sands a little, just thinking through the consistency and convention of how we write this as we're going. Something I've shifted to is a very pernickety / potentially annoying thing is having the branch name convention of rmbielby/main and mzateddfe/main instead of using the underscore. It's probably a superfluous tweak, but I feel like it could just make things parse a little more clearly when people are working through it.

[rmbielby]

I think lets use the specific example here, so use git add git-academy-log.md

[rmbielby]

GitHub is a flavour of DevOps, so saying "GitHub or DevOps" will get a strange look from anyone who happens to be a bit more familiar with what DevOps is. Doesn't matter so much for the level of user we're aiming at here, but worth changing this to "GitHub or Azure DevOps".

[rmbielby]

It's important to commit, but you don't need to push before switching branches.

[rmbielby]

Let's give an explicit demo here, we want everything to be practically lead. So git checkout main and then a line saying "check the git-academy-log.md" file and you'll see your edits have disappeared", then run git checkout <github_username>/main and you'll see your edits will return.

[rmbielby]

I'd be tempted to stick with checkout for the work through (given we've already introduced it for creating new branches). Then maybe add a line at the end saying "Alternatively, the git switch command can generally be used interchangeably with the git checkout command for switching branches."

[rmbielby]

At this point in the work through, they should really be on <github_id>/main already, so I think the steps here would again be: switch back to main, see your changes have been undone, then switch back to your own main branch.

[rmbielby]

As above, I think assume at this stage that they'll be progressing through linearly so will be on their own branch already.

[rmbielby]

Could keep the pattern from the previous pages here and say something like:

"Now you've made and recorded some changes on your working branch, we can look at how to move between branches and what that looks like in terms of file changes."

[mzayeddfe]

A few more ideas for this one. Sorry if this feels like shifting sands a little, just thinking through the consistency and convention of how we write this as we're going. Something I've shifted to is a very pernickety / potentially annoying thing is having the branch name convention of rmbielby/main and mzateddfe/main instead of using the underscore. It's probably a superfluous tweak, but I feel like it could just make things parse a little more clearly when people are working through it.

i ended up changing <github_username>_main and <github_id>_main variations to <github_username>/main even in scripts that i wasn't working on. hope that's ok!