diff --git a/Contribution-Technical-Practices.md b/Contribution-Technical-Practices.md new file mode 100644 index 0000000..d4fdd35 --- /dev/null +++ b/Contribution-Technical-Practices.md @@ -0,0 +1,137 @@ +Oh-My-Zsh is a community-driven project and contributions are welcome, but it all works +best with a proper setup. Here follow the best practices for setting up a fork and +getting started for contributing. + +### Prerequisites + +You will of course need Git and a UNIX terminal. You should be familiar with the basics of +[contributing on GitHub](https://help.github.com/articles/using-pull-requests). + +You will have to make a choice, whether you simply want to properly send PRs, or if you +also wish to maintain your own fork (with your own changes) as a personal alternative +version of OMZ. Think about it, it will come around later on. + +The following section explains how to set up your local Oh-My-Zsh install with the proper +[remote repositories](https://help.github.com/categories/managing-remotes/). + +### Setting up + +_From this point on,_ `` _stands for your GitHub username._ + +* **1.** Fork the original repository (button at the top of +[the repo's page](https://github.com/robbyrussell/oh-my-zsh)). + +_This supposes that you have Oh-My-Zsh installed already in `$ZSH` (default:_ +`~/.oh-my-zsh`_) with the origin remote pointing to the original repository._ + +* **2.** Now make the choice: either we keep it easy and simple, need-to-know basis, or you +take the red pill, and you stay in Wonderland _etc_. Here follows a manichaean dichotomy: + * **Blue pill:** auto-upgrade works, and you can send clean PRs; but your fork is not + maintained and you are not using your own master branch + * **Red pill:** you can send clean PRs, maintain your own fork with changes, use and + share your master branch; but auto-upgrade will not work + +#### Blue pill setup + +_All the following uses_ `` _for the remote name, but you can use something else._ + +* **3.** Go to your local install directory and add your own repository as a remote +```zsh +cd $ZSH +git remote add git@github.com:/oh-my-zsh.git +``` + +**Upgrading:** as long as your local master branch cleanly follows origin/master (which +still points to the original repository), auto-upgrade should work fine. + +**More setups:** on a new machine, simply install OMZ as usual, do step 3, and of course +copy your [startup files](http://zsh.sourceforge.net/Intro/intro_3.html); you will be +able to get upgrades, and to work on your pending PRs. + +[**Sending PRs**](#blue-pill-prs) + +#### Red pill setup + +* **3.** Go to your local install directory and rename the origin remote to "upstream" +```zsh +cd $ZSH +git remote rename origin upstream +``` +* **4.** Then set your own repository as the origin remote +```zsh +git remote add origin git@github.com:/oh-my-zsh.git +``` + +**Upgrading:** +* **Upstream:** when you want to get the latest upgrades from the original repository +(_aka_ upstream), simply `git pull upstream master`; you may have to solve conflicts with +your own changes of course; when you are satisfied with the update you can +`git push origin master`. +* **Origin:** when you want to get the latest upgrades from your own fork (_aka_ origin), +simply `git pull --rebase origin master`; you may have to solve conflicts with your local +changes of course; when you are satisfied with the update you can +`git push --force origin master`. + +**More setups:** on a new machine, simply +`git clone git@github.com:/oh-my-zsh.git ~/.oh-my-zsh` and +`git remote add upstream git@github.com:robbyrussell/oh-my-zsh.git`, and of course +copy your [startup files](http://zsh.sourceforge.net/Intro/intro_3.html); you will be +able to get upgrades, and to work on your pending PRs. + +[**Sending PRs**](#red-pill-prs) + +### Pull Requests + +_These are technical instructions, please read the_ +[contributing guidelines +(project)](https://github.com/robbyrussell/oh-my-zsh/pull/3770) _before sending PRs._ + +_The following uses_ `my-new-pr` _for the branch name, but you can use something else._ + +#### Blue pill PRs + +* **1.** Any new PR must start from a clean upstream tree +```zsh +git checkout origin/master +git checkout -b my-new-pr +``` + +You are now on your dedicated PR branch. Time to commit some changes! + +* **2.** Send your commits +```zsh +git push my-new-pr +``` + +You can now go to GitHub and create the PR. + +**Updating:** in case there are conflicting changes upstream after you created the branch, +you will have to `git pull --rebase origin master` on `my-new-pr` branch and resolve +conflicts, and then `git push --force my-new-pr`, in order to keep your PR up to date. + +**More setups:** on another machine, simply `git checkout /my-new-pr` and +`git checkout -b my-new-pr` to continue working on a pending PR. + +### Red pill PRs + +* **1.** Any new PR must start from a clean upstream tree +```zsh +git checkout upstream/master +git checkout -b my-new-pr +``` + +You are now on your dedicated PR branch. Time to commit some changes! + +* **2.** Send your commits +```zsh +git push origin my-new-pr +``` + +You can now go to GitHub and create the PR. + +**Updating:** in case there are conflicting changes upstream after you created the branch, +you will have to `git pull --rebase upstream master` on `my-new-pr` branch and resolve +conflicts, and then `git push --force origin my-new-pr`, in order to keep your PR up to date. + +**More setups:** on another machine, simply `git checkout origin/my-new-pr` and +`git checkout -b my-new-pr` to continue working on a pending PR.