NOTE: This chapter assumes that you are NOT a collaborator and can only contribute through pull requests. If you are a collaborator, you do not need to fork the app.
The Ruby on Racetracks elements (such as scripts and certain gems) are essential for me. However, the people in charge of a project may consider these elements unnecessary and want to keep them out of the master branch of the repository.
This chapter explains how to provide the Ruby on Racetracks elements for yourself while keeping them OUT of the pull requests you make.
The Usual Forking Procedure
To contribute to an app when you are NOT a collaborator, you fork the app, create a branch for your changes, and submit your branch in a pull request.
This procedure does NOT address how to save elements for yourself while keeping them out of pull requests.
What To Do Now
Go to the Rails app's main source code page on GitLab/BitBucket/GitHub. Let's call this app other_user/project1. Do NOT git clone the source code.
Fork this app. Let's call this app your_username/project1.
Go to the main source code page of your fork your_username/project1.
Start a Docker container from the Rails app's custom Docker image. In the /home/winner/shared directory, use the "git clone" command to download the Rails app. You now have the master branch of your_username/project1.
Enter the root directory. Enter the command "git remote -v". The URL printed should be that of YOUR fork of the source code and NOT that of the mainline version.
Master Branch of Fork
In your fork, keep the master branch EXACTLY the same as the master branch of the main app. Any differences between your master branch and the master branch of the main app end up in EVERY pull request you'll ever make.
The only change you should EVER make to the master branch of your fork is syncing it with the master branch of the main app.
All other changes belong in the ruby_on_racetracks branch or other branches.
Merge Conflicts
You may occasionally have merge conflicts between the master branch and ruby_on_racetracks branch. Hopefully, they will be easy to resolve.
When in doubt, favor the master branch way of doing things.
If the mainline source code does not use the annotate gem, do NOT add it to the ruby_on_racetracks branch. Because it edits so many files, it increases the risk of merge conflicts. If you want to have the annotate gem, start a separate branch for that. If the merge conflicts become too much to handle, you can delete this alternate branch and start a new one while leaving the ruby_on_racetracks branch alone.
What To Do Later
NOTE: Don't start on the actions in this section just yet. You will be implementing them in later chapters and units.
In your fork, you will create the branch ruby_on_racetracks and add the Ruby on Racetracks elements there. (The rest of Unit 2 covers this.) Git add, commit, and push these changes. (Be prepared to update this branch periodically from your fork's master branch.)
From the ruby_on_racetracks branch, start a new branch new_feature.
In the new_feature branch, make the necessary changes. Use the git_check.sh script to test everything. If all goes well, add, commit, and push these changes.
Enter the command "git log" and record the commit numbers of just the commits pertaining to the new feature.
Enter the command "git checkout master; git checkout -b pr_new_feature". (In other words, just add "pr_" to the beginning of the name of the branch of your new feature.)
Use the "git cherry-pick" command to select the changes from the new_feature branch you wish to add to the pr_new_feature branch. If you have more than one commit to add, make sure to add them in chronological order. (Note that the "git log" command lists the commits in reverse order.)
Add, commit, and push your changes to your pr_new_feature branch.
Make a pull request for your pr_new_feature branch.