Using Branches, Pull Requests, and Merging

🌳 Using Branches, Pull Requests, and Merging

Unfortunately GitHub's fix of a bug made the image URLs below not work. Most of this page makes sense without the images, but if you have the time please edit this page and replace the images!

Theory

• The GitHub Flow - Please read this article first.

As a team, we're using GitHub branches in a specific way to organise features, test them one-by-one, and only merge them into the main branch when a feature / bug-fix has been tested: Here's where the true power of Git and GitHub for collaborative coding starts to become visible. You're likely only to need the "Our Flow: Coding" section but please feel free to refer to all of this when you need it.

Table of Contents
Our Flow: Coding
Our Flow: Testing / Bug Fixing
(Advanced) Updating a feature's branch with code from the main branch

Our Flow: Coding

Here's an in-depth visual explanation of our approach, and this is how you should implement each feature from the Project. It can be annoying at first, but is a technique that is widely used, avoids buggy code ending up in our robot while playing and makes testing easier.

Image	Description
From GitHub Training Kit, Open-Source and © 2022 GitHub, Inc. Modified.	Our approach incorporates testing and team development into the GitHub Flow.
	In a session, a team/person is assigned a task (GitHub Issue) from the Project. They choose who will do what part of the task, by @mentioning usernames in the Issue description. Also add these people as "Assignees" to the right and click "Comment". Drag the task into "To Do".
	The team creates a new branch from the main branch, named in a sensible way that represents their task (e.g. computer-vision-navigation or arm-setpoints). Do this by clicking the "Open in New Tab" button to the right of an Issue in the Project, then clicking "Create a Branch" under the "Development" area on the right. Rename the default name shown to a more logical one, in this case swerve-tank-drive. Ensure "Open branch with GitHub Desktop" is selected.
	If this notification opens, ensure the box is ticked and click "Open". Otherwise, just open GitHub Desktop.
	Ensure you are on the correct branch for your feature by clicking "Current branch" if it is wrong and selecting the correct one.
	Code, commit and push as normal (see Saving and Uploading Code). Your team members' and your commits should appear in the History tab, just for the feature on this branch (click "Fetch origin" and try again if they don't). Other branches and features do not interfere with your testable code for this feature.
	When it is time to test code, or you have finished a feature as a team, you can start to submit a pull request. Click "Preview Pull Request" in GitHub Desktop and ensure that all of the code changes are correct, and that the "base" branch is "main". Now click "Create Pull Request". Then, drag the task into the "To Test" section of the GitHub Project.
	You will have a page from GitHub.com open. Type a description then click "Create Pull Request".
	You have now created a public pull request page that can be used for testing! Once testing has been finished, as a team we will check for bugs then merge your changes into the main branch - please do not click "Merge" yourself. The main branch will contain bug-free production-ready tested code only so can be used in our actual matches!

Our Flow: Testing / Bug Fixing

Image	Description
	We will never merge code to the main branch without testing (unless we're rushing in a competition). The main branch should only contain tested, production-ready code so drivers can use our latest features whenever they want without bugs.
	To find the list of pull requests, navigate to the code repository (please check it is the off-season one if applicable) and under the "Pull Requests" tab click the name of the feature you want to test.
and repeat for each file.	Only if "This branch has conflicts that must be resolved" shows up, click "Resolve Conflicts", and for each file keep only one version of the code for each instance of the yellow-highlighted-line-numbers and then click "Mark as resolved". When you have done this for all files, click "Commit merge", and ensure that you commit these changes into your feature branch if you are given the option. Click the "Pull" button in GitHub Desktop.
	Before merging the pull request, you must run the code on the robot (see here for how to test), and commit any bug fixes to the feature branch with GitHub Desktop. Click "Push" on GitHub Desktop to upload your bug fixes, and when you reload the pull request page the bug-fix commits should be visible.
	If necessary, write notes by commenting on the pull request. If for some reason this pull request does nothing, explain why then click "Close with comment" to delete it. This should rarely be needed.
	Once all bugs have been fixed and each part of the code has been thoroughly tested on an actual robot, click "Merge pull request" and "Confirm merge". This moves your code to the production-ready tested main branch. Then, drag the task into the "Done" section of the GitHub Project.

Updating a feature's branch with code from the main branch

Image	Description
	Sometimes you will want to merge code from the main branch (with already-tested features) to a work-in-progress branch for a feature. For example, one group has created an arm that works, and has been tested and merged to the main branch. Another group wants it in their branch for the drivetrain but does not have it, so they need to do the following:
	Go to our GitHub.com code repository, and under the "Pull Requests" tab click "New Pull Request".
	Ensure the "compare" branch is main and the base branch is the one for the feature that is currently being worked on, in this case the drivetrain. Now click "Create Pull Request".
	Write a description and click "Create Pull Request".
and repeat for each file.	Only if "This branch has conflicts that must be resolved" shows up, click "Resolve Conflicts", and for each file keep only one version of the code for each instance of the yellow-highlighted-line-numbers and then click "Mark as resolved". When you have done this for all files, click "Commit merge", and ensure that you "Create a new branch and commit updates". Name it _update- plus the name of the feature, in this case drivetrain.
	Click "Merge Pull Request", and click more buttons to merge the pull request.
	If you created an _update-feature branch because of conflicts, click "Delete branch".
	Open GitHub Desktop then click "Fetch" and "Pull". The features from the main branch should now be in your feature development branch. Now it's time to debug it, and write whatever you need to do in that new feature with the code from the main branch.