-
Notifications
You must be signed in to change notification settings - Fork 8
How to Contribute
If you'd like to make changes to the source code and have your changes available on the RoboTigers Heroku site then please follow these steps.
Fork & Pull Workflow
We are using a simple Fork & Pull Workflow. The way this works is that there are a number of repositories: The RoboTigers repository on Github, your Fork repository on Github, and a local repository on your laptop/PC. When your code is ready to be contributed back to RoboTigers you first commit your changes to your local repo and then push those changes to your Fork and finally you submit a Pull Request for the changes in your Fork to be merged into the RoboTigers repo.
Git Remotes
How do we manage all these repositories? Well our local git commands will work on our local git repository (git diff, git commit, etc) but how do we reach our Fork repo and the RoboTigers repo on Github? The answer is using "remotes" in git. The standard name for remotes you will need in a Fork & Pull workflow are "origin" and "upstream".
origin
When you did your clone of your fork, git automatically created for you a remote to your Fork in Github; it is called origin. If you use the git remote -v command you show see something like this:
/Users/sharon/RoboTigers/FRCScout2020$ git remote -v
origin https://github.com/sharonkass/FRCScout2020.git (fetch)
origin https://github.com/sharonkass/FRCScout2020.git (push)\
Make sure this origin fork points to YOUR github fork (not RoboTigers repo or any other developer's repo).
upstream
You will need to create a remote which points to the RoboTigers Github repo. You should create this remote:
git remote add upstream https://github.com/RoboTigers/FRCScout2020.git
Now when you list your remotes you will see upstream as well:
/Users/sharon/RoboTigers/FRCScout2020$ git remote -v
origin https://github.com/sharonkass/FRCScout2020.git (fetch)
origin https://github.com/sharonkass/FRCScout2020.git (push)
upstream https://github.com/RoboTigers/FRCScout2020.git (fetch)
upstream https://github.com/RoboTigers/FRCScout2020.git (push)
Branches
We will not be using branches. It adds confusion for our simple project. Your fork is a branch and it's default name is "master". So your local git repo is using the default branch named "master" and your Fork on Github has a default branch named "master" and ditto for the RoboTigers repo. You do not need to do anything but it is important to know since we will refer to "master" when we do our git pushes.
Other Developers
Other developers will have their own Forks and their own local repositories. So it is important to always make sure you have the latest RoboTigers repo updates in your local so that there are no conflicts when it is time to merge your changes into the RoboTigers repo.
Heroku
The RoboTigers Github repository has a hook into Heroku. This means that every merge into RoboTigers will automatically kick off a new release into Heroku. For more information on Heroku see the Heroku wiki.
It is possible that other developers have had their code changes merged into RoboTigers since you started making your changes on your local. If your changes are merged into RoboTigers without including the other developers' changes you will overwrite them and they will be lost. So you should be sure to pull all RobotTiger changes into your local before you pull. (You can and probably should commit your changes to your local first but for the purpose of these instructions we are keeping it simple and leaving out that step for the beginner audience)
From the terminal window:
cd FRCScout2020
git pull upstream master
This will pull any changes from RoboTigers github (upstream) into your local git repo. You must make sure to resolve any conflicts.
You can see what git thinks about the current state of your local repo:
cd FRCScout 2020
git status
You will notice your changes are not staged. You can add them using:
git add . <-- The dot indicates your current directory and is recursive
Sometimes we make code changes that we want to remove later (such as quick/local debugging stuff) and we forget to remove. We want to make sure that the code changes we submit are what we expect. Please use the Source Control feature of your IDE/Editor (or using git diff command line) to eyeball all your changes. Now is the time to clean up anything.
Please follow the steps in the Running the app locally wiki to make sure your changes work in your local.
It is fine to commit your changes locally and even push them to your Fork on Github (origin) to store them. But NEVER NEVER submit a Pull Request to have your Fork changes merged into the RoboTigers repo until you are sure they work properly.
You can save your changes (commit them) in your local git repo. Please use a proper message which is descriptive.
git commit -m"Add button to save Pit data"
Now your changes are safely stored in your local git. But your changes are only local, only on your laptop/PC. You must get them up to Github. If your laptop is lost then so are your changes.
Once your changes are committed to your local git repo then you can push them to your Fork repo on GitHub:
git push origin master
This tells git to push the changes in your local git repo to the origin remote (using default master branch). Note that git pull only looks in your local git repo. That is, if you make changes but do not commit them then they are not included in the push to origin.
Go to your forked repo on GitHub. For example: https://github.com/sharonkass/FRCScout2020 (Make sure you see your git username in the URL)
You will see a list of your commits. If you are ready to submit a Pull Request then click the "New Pull Request" button. (Take all defaults, do not change any buttons or anything)
You can scroll down and eyeball your changes. If everything looks good then click Submit.
Make sure to specify a reviewer. All Pull Requests require code review. Click "Reviewer" and select the name of the person you want to review your code.
The reviewer may have questions about your code or may ask you to make changes. These discussions happen directly on Github. Once the reviewer is satisfied they will click "Approve" and submit their review.
Once your Pull Request is approved nothing happens. It must be merged into the RoboTigers repo. The admin(s) will be notified and should quickly merge it for you. You can always reach out to them with a reminder :)
Once the repo admin merges your Pull Request code changes into the RoboTigers repo then a Heroku build will be kicked off. It should not take more than 5 minutes but be patient. You can follow progress of the Heroku release: https://dashboard.heroku.com/apps/robotigers-scout-2020/activity if you have the password for the RoboTigers Heroku login. It can be confusing though and risky if you also have your own heroku account so it is best to just wait. Reach out to an admin if you think it is taking too long.