Fork Upstream Repository
The premise is that each developer creates a fork of the nds-org (aka "upstream") source repository.
This can be accomplished by navigating to https://github.com/nds-org/nds-labs/tree/v2 and clicking on the "Fork" button at the top-right.
(You did create a GitHub account, didn't you? If not, see *New Developer Workflow.)
Clone from Origin Repository
The developer the can make any create or delete any branches they want on their own personal fork (aka "origin").
To make modifications to the code, the developer clones their origin repository.
This creates a local working copy of the code that is independent of your personal fork.
Clone the repository (and specify the "upstream repository") with the following commands:
git clone https://github.com/your-git-username/nds-labs.git cd nds-labs/ git remote add upstream https://github.com/nds-org/nds-labs.git
Commit Local Modifications
Make sure if you create any new files that you want Git to track, call the following command:
git add <path>
Modify the code all you want and when you are ready to commit to your local copy:
git commit -a -m "Enter a short description of your commit here."
Any changes that they wish to contribute back to the upstream repository can be made in the form of a Pull Request.
An administrator can then review the pull request before merging it in, and may ask you to modify your pull request before they will do so.
Push Committed Changes to Your Origin
Once you have a few commits gathered, you'll likely want to save them indefinitely by pushing them back to your personal fork.
Pushing to your fork does several things for you:
- it allows you to preserve your code on GitHub.com indefinitely
- it encapsulates any branches that you have made in a repo that only you can administrate.
- it allows others to easily pull in your code remotely for integration testing - just as we added the "upstream" remote with the git remote command, we can add any other developer's personal fork
- it enables you to create a Pull Request back to the upstream repo, contributing changes back for us to review and incorporate
WARNING: BE SURE that you want to push whatever push whatever you push.
It is VERY DIFFICULT to remove things from GitHub.com safely once they are pushed there.
Contribute Back with Pull Requests
When you think you have a change that NDS would benefit from, feel free to contribute it back to our repository at https://github.com/nds-org/nds-labs.git in the form of a Pull Request.
To make a Pull Request, navigate to your forked repository: https://github.com/your-git-username/nds-labs.git and click one of the several "Pull Request" button to Create a New Pull Request.
You can choose the source and destination remote and branch from here, as well as name your PR and enter a short description if you'd like.
In general, we tend to name Pull Requests after JIRA tickets, if the issue we are addressing has one associated with it. For example: NDS-101: Summary of JIRA Ticket
In the description, I normally like to link to the JIRA ticket as well, if one exists.
Undoing your Last Commit
Locally
If you accidentally commit something you ought not have, but have not yet pushed the commit to your personal fork, run the following command to undo the commit:
git reset HEAD^
The ^ tells git to reset to "the previous commit before head." You can chain together multiple ^'s to go back to the nth previous commit, but I would not recommend this unless you know what you are doing.
On Personal Fork
If you have already pushed the change to your personal fork, then you may be out of luck.
If the mistaken change that you made on a separate branch, you may need to delete the branch from your GitHub.com fork before restting with the above command.
If you made the mistaken change to master, then the only option to remove it may be to delete your entire personal fork and re-fork the upstream repo.
WARNING: Make sure to have any outstanding Pull Requests MERGED before deleting your personal fork, or your changes may get lost.