diff --git a/Contribution-Technical-Practices.md b/Contribution-Technical-Practices.md index b2ef281..a2e5bc9 100644 --- a/Contribution-Technical-Practices.md +++ b/Contribution-Technical-Practices.md @@ -1,137 +1,108 @@ -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. +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 +## 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 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. +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/). +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 +## 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)). +- **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._ +_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 -want a fully maintained fork with your own changes. Here follows a binary dichotomy: - * **Simple contribution:** auto-upgrade works, and you can send clean PRs; but your fork is not - maintained and you are not using your own master branch - * **Maintained fork:** you can send clean PRs, maintain your own fork with changes, use and - share your master branch; but auto-upgrade will not work +- **2.** Now make the choice: either we keep it easy and simple, need-to-know basis, or you want a fully maintained fork with your own changes. Here follows a binary dichotomy: + - **Simple contribution:** auto-upgrade works, and you can send clean PRs; but your fork is not maintained and you are not using your own master branch + - **Maintained fork:** you can send clean PRs, maintain your own fork with changes, use and share your master branch; but auto-upgrade will not work -#### Simple contribution setup +### Simple contribution 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 +- **3.** Go to your local install directory and add your own repository as a remote +```shell 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. +**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. +**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**](#simple-contribution-prs) -#### Maintained fork setup +### Maintained fork setup -* **3.** Go to your local install directory and rename the origin remote to "upstream" -```zsh +- **3.** Go to your local install directory and rename the origin remote to "upstream" +```shell cd $ZSH git remote rename origin upstream ``` -* **4.** Then set your own repository as the origin remote -```zsh + +- **4.** Then set your own repository as the origin remote +```shell 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`. +- **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. +`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**](#maintained-fork-prs) -### Pull Requests +## Pull Requests _These are technical instructions, please read the_ -[contributing guidelines -(project)](https://github.com/robbyrussell/oh-my-zsh/pull/3770) _before sending PRs._ +[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._ -#### Simple contribution PRs +### Simple contribution PRs -* **1.** Any new PR must start from a clean upstream tree -```zsh +- **1.** Any new PR must start from a clean upstream tree +```shell 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 +- **2.** Send your commits +```shell 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. +**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. +**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. -#### Maintained fork PRs +### Maintained fork PRs -* **1.** Any new PR must start from a clean upstream tree -```zsh +- **1.** Any new PR must start from a clean upstream tree +```shell 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 +- **2.** Send your commits +```shell 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. +**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. +**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.