Ideas on branching for collaborations

[andrealaw]

Hi everyone, to avoid crashing between commits, let's setup some branches.

Suggestions

1. By person (from @anglyeds)
2. By feature (from @gregorywong)

Based on our current status, indeed it could be a mix of both. First group by feature and hotfix, followed by a person's name. Then, merge commits between the team members and merge it to the feature branch.

Sample branch and subbranch names

v0.1-dev

• feature-navbar
  --feature-navbar/greg
  --feature-navbar/jeff
• feature-event
• feature-about
• hotfix-1
• hotfix-2 (where 2 is the issue number assigned by Github on the issue page)

Some ideas

• keep the branch names short and meaningful
• Urgency: hotfix > feature
• hotfixes are commited to the master branch directly
• features are commited to the version branch, e.g. feature-navbar -> v0.1-dev
• master branch is the production version for a Github page
• completed branches will be merged into their parent branches and get removed (commit history will be preserved with Git)

Sample commit message

Always use the original verb form, e.g. add/move/update:

Move How to Contribute to documentation and update it (#7817)

where #7817 is the issue number you can find on the issue page for each item.

Some reference

https://www.atlassian.com/git/tutorials/using-branches (Official)
https://github.com/agis/git-style-guide
https://gist.github.com/digitaljhelms/4287848

What do you guys think?

[gregorywong]

Thanks @andrealaw for summarizing and outlining the plan!

I have some thoughts about committing hotfixes directly to the master branch (under 'Some ideas'). It's good to be able to fix bugs quickly, but it will also mean that the changes don't get reviewed and might introduce other bugs. Perhaps, we should allow hotfixes to be committed directly to master, but it shouldn't be a requirement. (E.g., if people aren't confident that it won't break something, they can still make a hotfix-... branch and issue a pull request so someone can review it).

I also wonder if there's a better way to find which issue the branch refers to. (Right now, it seems like we'd have to look it up in the issues section manually?)

[andrealaw]

I found those who are working on the ReactJS Github repository use commit message to track issues. However, we can try something simple first.

How about we setup branches with issue ids to keep it simple? As branches are usually temporary and will get removed from the main page once they get merged to the master branch or their parent branches.

Sample initial branches:
issue-3
issue-8
issue-6

We can try other approaches later on if it does not work.

[andrealaw]

Also, I agree with your suggestion on hotfixes. I guess we need some instructions for contributors to learn how to do a pull request. @gregorywong

[gregorywong]

@andrealaw Sounds like a plan. I'll try doing a simple one later and submit a pull request.

[anglyeds]

Hey guys , I guess we need a person who handle the conflicts merging problem. Because if there is someone who does not pull the latest master branch , it will somehow conflicted the master branch with his own branch. So, do you guys have any other suggestion towards this matter ?

[gregorywong]

@anglyeds
So my understanding is that right now, when people work directly on master, they're unable to push to GitHub when there's a conflict. That means the code is stuck on their computer and no one else can help them resolve the issue.

One way to improve the situation (but not completely fix it) would be to create branches for separate issues and work on those branches (and not master). Using such a workflow, people should always be able to push to GitHub without any merge issues (assuming they are the only ones working on that branch). There would still be conflicts when merging those branches with master, but since the code is already up on GitHub, others can always step in and help if necessary.

Meanwhile, I will be looking through this guide to see if we can adopt practices from them: https://opensource.guide/

[isaackwan]

Hey, sorry 've been busy with school in the past few days. Just wanted to chime in with a few different perspectives with regards to Git/VCS.

Should there a place where we document guidelines for new and old contributors?

Yes definitely! However the best place to do this might be the CONTRIBUTING file. Making sure that we align with this convention has the added advantage that GitHub will pick it up and show it to users:

Should we set up some sort of naming convention for branch names?

Well...... this practice make sense, but its effect is much less than one might think because most Git branches are short-lived. In Git (and especially the GitHub universe), branches are often removed after the PR is accepted, and a helpful button for deleting the branch will appear in the PR page once the PR is accepted:

What happens when merge conflict happens?

This is a very legit concern. Fortunately, there are two important tools at our disposal that practically makes this a non-issue. First is traditional conflict resolution, where a maintainer can step in and resolve the conflict. GitHub provides an online tool for this purpose. More often though, maintainer might not want to get his/her hand dirty and would leave this to the PR proposer instead. S/he would then rebase his changes, resolve any potential conflict, and push it to the new branch. The new PR then becomes conflict-free.

Is there a feature that allows us to categorize branches, with the example being hotfix-10-gregorywong?

Yes! In the Git world it's conventional to categorize branches with its type, such as bugfix, develop, etc. We would do something like develop/change-github-link. If you use a Git GUI (see below for an example) you can easily collapse and group different types of branches if you use this convention.

Should we create branches at the public FCCHK repo, or in our own private forks (e.g. commit in isaackwan/FreeCodeCampHongKong.github.io and open a PR)?

The OSS world seem to prefer the latter. My guess is that it allows a cleaner Git history on the project level. Indeed, when there is a major new release, collaboration is essential and a public branch would be very helpful. An example can be seen here.

Can I create multiple commits for fixing one issue?

OSS people seem to be over-obsessed with cleanness and seems to prefer that you do so. (If you want an over-engineered explanation on this please click me). What this means in translation is that

• As a maintainer, when you accept PR's, click on the squash and merge button when you accept a PR.
• When you commit code to master directly, learn to use some commands (e.g. Git rebase with squash or git reset) to make sure that only one commit is created for your issue. (Or better yet, branch and open a PR).

Is there a software package that helps me visualize all this mess? I am VERY confused!

If visualization is important to you then I strongly recommend you check out SourceTree, which is the only software I missed when I switched to 100% Linux. It helps one to not only visualize the Git tree but also gain familarity with different concepts without the hassle of a CLI. Gitk, built-in in many Git installations, comes close but is not as newbie-friendly.

Thanks for making this far -- please definitely let me know if this is helpful to you! :)

[isaackwan]

BTW - if your PR/commit message follows a specified format, the associated issue can be closed automatically when the PR is accepted, (saving you a whopping one click.)

[gregorywong]

@isaackwan Thanks for the detailed writeup! I finally managed to go through all of it 😆

Here's my two cents on it:

1. CONTRIBUTING file
   That's an excellent idea! I guess I can move what we have right now to that file, and then any subsequent edits can be made there?

2. Branching for edits
   Agree that naming doesn’t have to be strict, since branches are created and deleted all the time.
   But we should definitely work on issues on other branches and not directly on master.
   This is now pretty much enforced, since we were able to disable direct commits to the master branch (all changes must be made using PR). Although it has its drawbacks (people not being able to make small changes quickly), it helps protect us from accidental commits to the master branch.

3. Creating branches at the public FCCHK repo vs. in our own private forks
   I think we should recommend people use private forks, but still allow for both.
   While using private forks makes things cleaner, the benefits of creating public branches on FCCHK is that other members can help out if necessary. It would be complicated to do so on someone’s private fork.

Also, do you have any suggestions / ideas on how we should organize all of this information? E.g., where to display it so that it's accessible to people who haven't been as involved?