Move/Rewrite Ambiguous Note in the 'Github Issues' Step

[JLKwong]

Problem

Right after the instructions to create a new branch, there is a note telling the user that "Everytime you create a new branch, make sure that you switch to master branch using the command git checkout master". Then, it tells the user to redo the steps to create a new branch, "then follow the above steps to avoid creating a branch off other branch."

As you can see, if a user just created a new branch, then they would follow this note by switching to the master branch and/or trying to recreate a new branch before they even commit/push their new branch. This could lead to a lot of errors/roadblocks for the user, and bad pushes for the repo.

Steps to reproduce the problem

N/A

Screenshots

Proposed solution

2 possible solutions:

1. Move the note to before the first step to create a new branch, and revise the text to read:

NOTE: If you just created a new branch, switch back to master branch using the command git checkout master to avoid creating a branch off other branch. Your master branch is the base working branch. It needs to remain untouched just in case you need to revert some changes back to a working version. Make sure you are on the right branch using git branch to see what branch you are currently on, and git checkout branch-name to switch to the a proper branch before making changes to your local files and committing.

2a. Add a new first step to creating a new branch that reads:

1. Switch to master branch with git checkout master. (If you are already on master, then move to the next steps.)

2b. AND revise the note to read:

NOTE: Your master branch is the base working branch. It needs to remain untouched just in case you need to revert some changes back to a working version. Make sure you are on the right branch using git branch to see what branch you are currently on, and git checkout branch-name to switch to the a proper branch before making changes to your local files and committing.

[rjpadilla]

I think you misread the steps.

It says (make note of the emphasis):

Everytime you create a new branch, make sure that you switch to master branch using the command git checkout master, then follow the above steps to avoid creating a branch off other branch.

I think its the last part of the sentence you skipped over. The note is just a reminder to always be using the master branch when creating new issue branches. The logic behind this is that you don't want to be working on a dirtied branch and still have a savepoint to return to if you made a mistake in your commits.

What is a dirtied branch (I made this up by the way, don't know if there is a real term for it)?
A dirtied branch is a branch that has commits that are not suppose to be part of the workflow.
Imagine you are working on branch issueOne (and done some commits by the way) and decided to work on issueTwo, so you create a new branch git branch issueTwo then git checkout issueTwo . Sounds good right?

But this is wrong. You are not only commiting on issueTwo, but inherently ALL the commits from branch issueOne as well.

You've never switched out of issueOne.

If a team member denies branch issueOne but approves branch issueTwo, you are literally cheating the team member by secretly adding unapproved commits to the git workflow.

This is why anytime we want to create a new branch, we start by creating it in the master branch and not the issue branch.

In my opinion, the only solution to make the note more clearer is to move the note untouched (minus the last part from the quote above) above the Create a New Branch heading. I feel that if you revise the note with your solution, interns may end up with a dirtied issue or master branch...

[JLKwong]

I think you misread the steps.

It says (make note of the emphasis):

Everytime you create a new branch, make sure that you switch to master branch using the command git checkout master, then follow the above steps to avoid creating a branch off other branch.

I think its the last part of the sentence you skipped over.

Just so I understand, are you saying that it is intended that users:

1. Follow the steps to create a new branch
2. Switch back to the master branch using git checkout master
3. Follow the steps to create a new branch again (per the quoted note, "then follow the above steps to avoid creating a branch off other branch")
4. Follow the steps to commit and push

Keep in mind that if a user just created a branch, and hasn't committed or pushed anything yet, they're not sure why proceeding to the commit/push steps would 'create a branch off other branch', and therefore 'follow the above steps' before committing/pushing. The way it is phrased now, it could be interpreted that it is necessary to repeat the creating branches step before committing/pushing because it would 'avoid creating a branch off other branch'.

What do users do when they get an error saying the branch is already created?
If a user just created a new branch, why is it necessary to switch back to master, then switch back to the newly created branch before committing/pushing?
What would happen if users just create the branch, commit and push, and then switch back to the master branch?

The note is just a reminder to always be using the master branch when creating new issue branches.

Yes, the point of this issue is to make that clear.

The way it is positioned/written now, it is unclear that the user should be switching to the master branch before creating new branches, not right after. If they switch to the master branch right after, the user has to decide between:

1. following the note to redo the steps to recreate the branch which, as mentioned above, would generate an error message, or
2. commit from the master branch

Neither of the above scenarios are productive, so it's best to simply make it clear that users should switch to the master branch before creating new issue branches, especially for those without prior experience in version control management.

The logic behind this is that you don't want to be working on a dirtied branch and still have a savepoint to return to if you made a mistake in your commits.

What is a dirtied branch (I made this up by the way, don't know if there is a real term for it)?
A dirtied branch is a branch that has commits that are not suppose to be part of the workflow.
Imagine you are working on branch issueOne (and done some commits by the way) and decided to work on issueTwo, so you create a new branch git branch issueTwo then git checkout issueTwo . Sounds good right?

But this is wrong. You are not only commiting on issueTwo, but inherently ALL the commits from branch issueOne as well.

You've never switched out of issueOne.

If a team member denies branch issueOne but approves branch issueTwo, you are literally cheating the team member by secretly adding unapproved commits to the git workflow.

This is why anytime we want to create a new branch, we start by creating it in the master branch and not the issue branch.

I'm not sure why you wrote this essay, but I appreciate it. 😌👍 While your tutorial is very explicit, it's a bit too verbose for a note. When you specify how you could fit this in the page, I'll be more than happy to modify my proposed solution accordingly.

In my opinion, the only solution to make the note more clearer is to move the note untouched (minus the last part from the quote above) above the Create a New Branch heading. I feel that if you revise the note with your solution, interns may end up with a dirtied issue or master branch...

Good catch. I will remove the last sentence of the note in my proposed solution.

Can you help me understand why you would leave the first sentence unchanged? I, and many others, would get confused by the first sentence if the note was moved to before the steps to create a new branch. It reads as follows:

Everytime you create a new branch, make sure that you switch to master branch using the command git checkout master, then follow the above steps to avoid creating a branch off other branch.

In addition to the clarity issue I mentioned earlier, it's not clear what 'above steps' refers to if the note gets moved above the steps to create a new branch.

Besides the first and last sentence, your solution is similar one of my proposed solutions:

1. Move the note to before the first step to create a new branch, and revise the text to read:

NOTE: If you just created a new branch, switch back to master branch using the command git checkout master to avoid creating a branch off other branch. Your master branch is the base working branch. It needs to remain untouched just in case you need to revert some changes back to a working version. Make sure you are on the right branch using git branch to see what branch you are currently on, and git checkout branch-name to switch to the a proper branch before making changes to your local files and committing. Use git status to check the changes that you made in your repository before making a commit.

Phew, this was a lot to respond to! Next time, if you could shorten your proposed solutions to just your solution (i.e. the last 2 sentences), instead of appending an entire essay before it (i.e. the 14 sentences that came before your solution), it would make it a lot easier for me to read and respond to it. Thank you for helping! :D

[JLKwong]

@rjpadilla I rephrased my issue to be more clear, and I deleted the last sentence of the note per your recommendation. Thank you for your feedback. 👍

[rjpadilla]

@JLKwong Ah sorry about the essay. I just added that there to make sure we were on the same page. It is by no means suppose to be an addition to your solution 😂 .

[JLKwong]

@rjpadilla 😂 No worries, I appreciate you making sure we're on the same page. When I saw all the text, I was like 😰. What else do you suggest for this issue?