|
| 1 | +Git workflow for yii2-markdown contributors |
| 2 | +=========================================== |
| 3 | + |
| 4 | +So you want to contribute to yii2-markdown? Great! But to increase the chances of your changes being accepted quickly, please |
| 5 | +follow the following steps. If you are new to Git and GitHub, you might want to first check out [GitHub help](http://help.github.com/), [try Git](https://try.github.com) |
| 6 | +or learn something about [Git internal data model](http://nfarina.com/post/9868516270/git-is-simpler). |
| 7 | + |
| 8 | +Setup the development environment |
| 9 | +--------------------------------- |
| 10 | + |
| 11 | +Assuming you already have a yii2 development environment, carry out the following steps to create a development environment for the repo. |
| 12 | + |
| 13 | +### 1. [Fork](http://help.github.com/fork-a-repo/) the yii2-markdown repository on GitHub and clone your fork to your development environment |
| 14 | + |
| 15 | +``` |
| 16 | +git clone [email protected]:YOUR-GITHUB-USERNAME/yii2-markdown.git |
| 17 | +``` |
| 18 | + |
| 19 | +If you have trouble setting up Git with GitHub in Linux, or are getting errors like "Permission Denied (publickey)", |
| 20 | +then you must [setup your Git installation to work with GitHub](http://help.github.com/linux-set-up-git/) |
| 21 | + |
| 22 | +> Tip: if you're not fluent with Git, we recommend reading excellent free [Pro Git book](https://git-scm.com/book/en/v2). |
| 23 | +
|
| 24 | +### 2. Add the main yii2-markdown repository as an additional git remote called "upstream" |
| 25 | + |
| 26 | +Change to the directory where you cloned yii2-markdown, normally, "yii2-markdown". Then enter the following command: |
| 27 | + |
| 28 | +``` |
| 29 | +git remote add upstream git://github.com/kartik-v/yii2-markdown.git |
| 30 | +``` |
| 31 | + |
| 32 | +### 3. Prepare the testing environment |
| 33 | + |
| 34 | +- You should have a working yii 2 development environment in which you have already installed `yii2-markdown` and includes latest and updated `yii2-markdown` fork from source. |
| 35 | +- Ensure you have the latest `dev-master` releases of all dependent extensions via your composer updates |
| 36 | +- Ensure you use the above cloned latest `yii2-markdown` code in your testing environment |
| 37 | + |
| 38 | +**Now you have a working playground for hacking on yii2-markdown.** |
| 39 | + |
| 40 | +Working on bugs and features |
| 41 | +---------------------------- |
| 42 | + |
| 43 | +Having prepared your development environment as explained above you can now start working on the feature or bugfix. |
| 44 | + |
| 45 | +### 1. Make sure there is an issue created for the thing you are working on if it requires significant effort to fix |
| 46 | + |
| 47 | +All new features and bug fixes should have an associated issue to provide a single point of reference for discussion |
| 48 | +and documentation. Take a few minutes to look through the existing issue list for one that matches the contribution you |
| 49 | +intend to make. If you find one already on the issue list, then please leave a comment on that issue indicating you |
| 50 | +intend to work on that item. If you do not find an existing issue matching what you intend to work on, please |
| 51 | +open a new issue or create a pull request directly if it is straightforward fix. This will allow the team to |
| 52 | +review your suggestion, and provide appropriate feedback along the way. |
| 53 | + |
| 54 | +> For small changes or documentation issues or straightforward fixes, you don't need to create an issue, a pull request is enough in this case. |
| 55 | +
|
| 56 | +### 2. Fetch the latest code from the main yii2-markdown branch |
| 57 | + |
| 58 | +``` |
| 59 | +git fetch upstream |
| 60 | +``` |
| 61 | + |
| 62 | +You should start at this point for every new contribution to make sure you are working on the latest code. |
| 63 | + |
| 64 | +### 3. Create a new branch for your feature based on the current yii2-markdown master branch |
| 65 | + |
| 66 | +> That's very important since you will not be able to submit more than one pull request from your account if you'll |
| 67 | + use master. |
| 68 | + |
| 69 | +Each separate bug fix or change should go in its own branch. Branch names should be descriptive and start with |
| 70 | +the number of the issue that your code relates to. If you aren't fixing any particular issue, just skip number. |
| 71 | +For example: |
| 72 | + |
| 73 | +``` |
| 74 | +git checkout upstream/master |
| 75 | +git checkout -b 999-name-of-your-branch-goes-here |
| 76 | +``` |
| 77 | + |
| 78 | +### 4. Do your magic, write your code |
| 79 | + |
| 80 | +Make sure you have first updated the testing environment as mentioned in [prepare-the-testing-environment][prepare-the-testing-environment]. |
| 81 | + |
| 82 | +Then make sure you have the updated code with your change and it works :). |
| 83 | + |
| 84 | +Unit tests are always welcome. Tested and well covered code greatly simplifies the task of checking your contributions. |
| 85 | +Failing unit tests as issue description are also accepted. |
| 86 | + |
| 87 | +### 5. Update the CHANGE log |
| 88 | + |
| 89 | +Edit the `CHANGE.md` file to include your change, you should insert this at the top of the file under the |
| 90 | +first heading (the version that is currently under development), the line in the change log should look like one of the following: |
| 91 | + |
| 92 | +``` |
| 93 | +Bug #999: a description of the bug fix (Your Name) |
| 94 | +Enh #999: a description of the enhancement (Your Name) |
| 95 | +``` |
| 96 | + |
| 97 | +`#999` is the issue number that the `Bug` or `Enh` is referring to. |
| 98 | +The changelog should be grouped by type (`Bug`,`Enh`) and ordered by issue number. |
| 99 | + |
| 100 | +For very small fixes, e.g. typos and documentation changes, there is no need to update the `CHANGE.md`. |
| 101 | + |
| 102 | +### 6. Commit your changes |
| 103 | + |
| 104 | +add the files/changes you want to commit to the [staging area](http://gitref.org/basic/#add) with |
| 105 | + |
| 106 | +``` |
| 107 | +git add path/to/my/file.php |
| 108 | +``` |
| 109 | + |
| 110 | +You can use the `-p` option to select the changes you want to have in your commit. |
| 111 | + |
| 112 | +Commit your changes with a descriptive commit message. Make sure to mention the ticket number with `#XXX` so GitHub will |
| 113 | +automatically link your commit with the ticket: |
| 114 | + |
| 115 | +``` |
| 116 | +git commit -m "A brief description of this change which fixes #999 goes here" |
| 117 | +``` |
| 118 | + |
| 119 | +### 7. Pull the latest yii2-markdown code from upstream into your branch |
| 120 | + |
| 121 | +``` |
| 122 | +git pull upstream master |
| 123 | +``` |
| 124 | + |
| 125 | +This ensures you have the latest code in your branch before you open your pull request. If there are any merge conflicts, |
| 126 | +you should fix them now and commit the changes again. This ensures that it's easy for the yii2-markdown team to merge your changes |
| 127 | +with one click. |
| 128 | + |
| 129 | +### 8. Having resolved any conflicts, push your code to GitHub |
| 130 | + |
| 131 | +``` |
| 132 | +git push -u origin 999-name-of-your-branch-goes-here |
| 133 | +``` |
| 134 | + |
| 135 | +The `-u` parameter ensures that your branch will now automatically push and pull from the GitHub branch. That means |
| 136 | +if you type `git push` the next time it will know where to push to. This is useful if you want to later add more commits |
| 137 | +to the pull request. |
| 138 | + |
| 139 | +### 9. Open a [pull request](http://help.github.com/send-pull-requests/) against upstream. |
| 140 | + |
| 141 | +Go to your repository on GitHub and click "Pull Request", choose your branch on the right and enter some more details |
| 142 | +in the comment box. To link the pull request to the issue put anywhere in the pull comment `#999` where 999 is the |
| 143 | +issue number. |
| 144 | + |
| 145 | +> Note that each pull-request should fix a single change. For multiple, unrelated changes, please open multiple pull requests. |
| 146 | +
|
| 147 | +### 10. Someone will review your code |
| 148 | + |
| 149 | +Someone will review your code, and you might be asked to make some changes, if so go to step #6 (you don't need to open |
| 150 | +another pull request if your current one is still open). If your code is accepted it will be merged into the main branch |
| 151 | +and become part of the next yii2-markdown release. If not, don't be disheartened, different people need different features and yii2-markdown |
| 152 | +can't be everything to everyone, your code will still be available on GitHub as a reference for people who need it. |
| 153 | + |
| 154 | +### 11. Cleaning it up |
| 155 | + |
| 156 | +After your code was either accepted or declined you can delete branches you've worked with from your local repository |
| 157 | +and `origin`. |
| 158 | + |
| 159 | +``` |
| 160 | +git checkout master |
| 161 | +git branch -D 999-name-of-your-branch-goes-here |
| 162 | +git push origin --delete 999-name-of-your-branch-goes-here |
| 163 | +``` |
| 164 | + |
| 165 | +### Command overview (for advanced contributors) |
| 166 | + |
| 167 | +``` |
| 168 | +git clone [email protected]:YOUR-GITHUB-USERNAME/yii2-markdown.git |
| 169 | +git remote add upstream git://github.com/kartik-v/yii2-markdown.git |
| 170 | +``` |
| 171 | + |
| 172 | +``` |
| 173 | +git fetch upstream |
| 174 | +git checkout upstream/master |
| 175 | +git checkout -b 999-name-of-your-branch-goes-here |
| 176 | +
|
| 177 | +/* do your magic, update changelog if needed */ |
| 178 | +
|
| 179 | +git add path/to/my/file.php |
| 180 | +git commit -m "A brief description of this change which fixes #999 goes here" |
| 181 | +git pull upstream master |
| 182 | +git push -u origin 999-name-of-your-branch-goes-here |
| 183 | +``` |
| 184 | + |
| 185 | +[prepare-the-testing-environment]: #3-prepare-the-testing-environment |
0 commit comments