huncholaneNot for normies
| 1 | # CONTRIBUTING GUIDELINES |
| 2 | |
| 3 | Oh-My-Zsh is a community-driven project. Contribution is welcome, encouraged, and appreciated. |
| 4 | It is also essential for the development of the project. |
| 5 | |
| 6 | First, please take a moment to review our [code of conduct](CODE_OF_CONDUCT.md). |
| 7 | |
| 8 | These guidelines are an attempt at better addressing the huge amount of pending |
| 9 | issues and pull requests. Please read them closely. |
| 10 | |
| 11 | Foremost, be so kind as to [search](#use-the-search-luke). This ensures any contribution |
| 12 | you would make is not already covered. |
| 13 | |
| 14 | <!-- TOC updateonsave:true depthfrom:2 --> |
| 15 | |
| 16 | - [Reporting Issues](#reporting-issues) |
| 17 | - [You have a problem](#you-have-a-problem) |
| 18 | - [You have a suggestion](#you-have-a-suggestion) |
| 19 | - [Submitting Pull Requests](#submitting-pull-requests) |
| 20 | - [Getting started](#getting-started) |
| 21 | - [You have a solution](#you-have-a-solution) |
| 22 | - [You have an addition](#you-have-an-addition) |
| 23 | - [Use the Search, Luke](#use-the-search-luke) |
| 24 | - [Commit Guidelines](#commit-guidelines) |
| 25 | - [Format](#format) |
| 26 | - [Style](#style) |
| 27 | - [Volunteer](#volunteer) |
| 28 | |
| 29 | <!-- /TOC --> |
| 30 | |
| 31 | ## Reporting Issues |
| 32 | |
| 33 | ### You have a problem |
| 34 | |
| 35 | Please be so kind as to [search](#use-the-search-luke) for any open issue already covering |
| 36 | your problem. |
| 37 | |
| 38 | If you find one, comment on it, so we know more people are experiencing it. |
| 39 | |
| 40 | If not, look at the [Troubleshooting](https://github.com/ohmyzsh/ohmyzsh/wiki/Troubleshooting) |
| 41 | page for instructions on how to gather data to better debug your problem. |
| 42 | |
| 43 | Then, you can go ahead and create an issue with as much detail as you can provide. |
| 44 | It should include the data gathered as indicated above, along with the following: |
| 45 | |
| 46 | 1. How to reproduce the problem |
| 47 | 2. What the correct behavior should be |
| 48 | 3. What the actual behavior is |
| 49 | |
| 50 | Please copy to anyone relevant (e.g. plugin maintainers) by mentioning their GitHub handle |
| 51 | (starting with `@`) in your message. |
| 52 | |
| 53 | We will do our very best to help you. |
| 54 | |
| 55 | ### You have a suggestion |
| 56 | |
| 57 | Please be so kind as to [search](#use-the-search-luke) for any open issue already covering |
| 58 | your suggestion. |
| 59 | |
| 60 | If you find one, comment on it, so we know more people are supporting it. |
| 61 | |
| 62 | If not, you can go ahead and create an issue. Please copy to anyone relevant (e.g. plugin |
| 63 | maintainers) by mentioning their GitHub handle (starting with `@`) in your message. |
| 64 | |
| 65 | ## Submitting Pull Requests |
| 66 | |
| 67 | ### Getting started |
| 68 | |
| 69 | You should be familiar with the basics of |
| 70 | [contributing on GitHub](https://help.github.com/articles/using-pull-requests) and have a fork |
| 71 | [properly set up](https://github.com/ohmyzsh/ohmyzsh/wiki/Contribution-Technical-Practices). |
| 72 | |
| 73 | You MUST always create PRs with _a dedicated branch_ based on the latest upstream tree. |
| 74 | |
| 75 | If you create your own PR, please make sure you do it right. Also be so kind as to reference |
| 76 | any issue that would be solved in the PR description body, |
| 77 | [for instance](https://help.github.com/articles/closing-issues-via-commit-messages/) |
| 78 | _"Fixes #XXXX"_ for issue number XXXX. |
| 79 | |
| 80 | ### You have a solution |
| 81 | |
| 82 | Please be so kind as to [search](#use-the-search-luke) for any open issue already covering |
| 83 | your [problem](#you-have-a-problem), and any pending/merged/rejected PR covering your solution. |
| 84 | |
| 85 | If the solution is already reported, try it out and +1 the pull request if the |
| 86 | solution works ok. On the other hand, if you think your solution is better, post |
| 87 | it with reference to the other one so we can have both solutions to compare. |
| 88 | |
| 89 | If not, then go ahead and submit a PR. Please copy to anyone relevant (e.g. plugin |
| 90 | maintainers) by mentioning their GitHub handle (starting with `@`) in your message. |
| 91 | |
| 92 | ### You have an addition |
| 93 | |
| 94 | Please [do not](https://github.com/ohmyzsh/ohmyzsh/wiki/Themes#dont-send-us-your-theme-for-now) |
| 95 | send themes for now. |
| 96 | |
| 97 | Please be so kind as to [search](#use-the-search-luke) for any pending, merged or rejected Pull Requests |
| 98 | covering or related to what you want to add. |
| 99 | |
| 100 | If you find one, try it out and work with the author on a common solution. |
| 101 | |
| 102 | If not, then go ahead and submit a PR. Please copy to anyone relevant (e.g. plugin |
| 103 | maintainers) by mentioning their GitHub handle (starting with `@`) in your message. |
| 104 | |
| 105 | For any extensive change, such as a new plugin, you will have to find testers to +1 your PR. |
| 106 | |
| 107 | ### New plugin aliases |
| 108 | |
| 109 | We acknowledge that aliases are a core part of Oh My Zsh. There are plugins that have +100 aliases! |
| 110 | |
| 111 | This has become an issue for two opposing reasons: |
| 112 | |
| 113 | - Some users want to have their personal aliases in Oh My Zsh. |
| 114 | - Some users don't want any aliases at all and feel that there are too many. |
| 115 | |
| 116 | Because of this, from now on, we require that new aliases follow these conditions: |
| 117 | |
| 118 | 1. They will be used by many people, not just a few. |
| 119 | 2. The aliases will be used many times and for common tasks. |
| 120 | 3. Prefer one generic alias over many specific ones. |
| 121 | 4. When justifying the need for an alias, talk about workflows where you'll use it, |
| 122 | preferably in combination with other aliases. |
| 123 | 5. If a command with the same name exists, look for a different alias name. |
| 124 | |
| 125 | This list is not exhaustive! Please remember that your alias will be in the machines of many people, |
| 126 | so it should be justified why they should have it. |
| 127 | |
| 128 | ---- |
| 129 | |
| 130 | ## Use the Search, Luke |
| 131 | |
| 132 | _May the Force (of past experiences) be with you_ |
| 133 | |
| 134 | GitHub offers [many search features](https://help.github.com/articles/searching-github/) |
| 135 | to help you check whether a similar contribution to yours already exists. Please search |
| 136 | before making any contribution, it avoids duplicates and eases maintenance. Trust me, |
| 137 | that works 90% of the time. |
| 138 | |
| 139 | You can also take a look at the [FAQ](https://github.com/ohmyzsh/ohmyzsh/wiki/FAQ) |
| 140 | to be sure your contribution has not already come up. |
| 141 | |
| 142 | If all fails, your thing has probably not been reported yet, so you can go ahead |
| 143 | and [create an issue](#reporting-issues) or [submit a PR](#submitting-pull-requests). |
| 144 | |
| 145 | ---- |
| 146 | |
| 147 | ## Commit Guidelines |
| 148 | |
| 149 | Oh My Zsh uses the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) |
| 150 | specification. The automatic changelog tool uses these to automatically generate |
| 151 | a changelog based on the commit messages. Here's a guide to writing a commit message |
| 152 | to allow this: |
| 153 | |
| 154 | ### Format |
| 155 | |
| 156 | ``` |
| 157 | type(scope)!: subject |
| 158 | ``` |
| 159 | |
| 160 | - `type`: the type of the commit is one of the following: |
| 161 | |
| 162 | - `feat`: new features. |
| 163 | - `fix`: bug fixes. |
| 164 | - `docs`: documentation changes. |
| 165 | - `refactor`: refactor of a particular code section without introducing |
| 166 | new features or bug fixes. |
| 167 | - `style`: code style improvements. |
| 168 | - `perf`: performance improvements. |
| 169 | - `test`: changes to the test suite. |
| 170 | - `ci`: changes to the CI system. |
| 171 | - `build`: changes to the build system (we don't yet have one so this shouldn't apply). |
| 172 | - `chore`: for other changes that don't match previous types. This doesn't appear |
| 173 | in the changelog. |
| 174 | |
| 175 | - `scope`: section of the codebase that the commit makes changes to. If it makes changes to |
| 176 | many sections, or if no section in particular is modified, leave blank without the parentheses. |
| 177 | Examples: |
| 178 | |
| 179 | - Commit that changes the `git` plugin: |
| 180 | ``` |
| 181 | feat(git): add alias for `git commit` |
| 182 | ``` |
| 183 | |
| 184 | - Commit that changes many plugins: |
| 185 | ``` |
| 186 | style: fix inline declaration of arrays |
| 187 | ``` |
| 188 | |
| 189 | For changes to plugins or themes, the scope should be the plugin or theme name: |
| 190 | |
| 191 | - ✅ `fix(agnoster): commit subject` |
| 192 | - ❌ `fix(theme/agnoster): commit subject` |
| 193 | |
| 194 | - `!`: this goes after the `scope` (or the `type` if scope is empty), to indicate that the commit |
| 195 | introduces breaking changes. |
| 196 | |
| 197 | Optionally, you can specify a message that the changelog tool will display to the user to indicate |
| 198 | what's changed and what they can do to deal with it. You can use multiple lines to type this message; |
| 199 | the changelog parser will keep reading until the end of the commit message or until it finds an empty |
| 200 | line. |
| 201 | |
| 202 | Example (made up): |
| 203 | |
| 204 | ``` |
| 205 | style(agnoster)!: change dirty git repo glyph |
| 206 | |
| 207 | BREAKING CHANGE: the glyph to indicate when a git repository is dirty has |
| 208 | changed from a Powerline character to a standard UTF-8 emoji. You can |
| 209 | change it back by setting `ZSH_THEME_DIRTY_GLYPH`. |
| 210 | |
| 211 | Fixes #420 |
| 212 | |
| 213 | Co-authored-by: Username <email> |
| 214 | ``` |
| 215 | |
| 216 | - `subject`: a brief description of the changes. This will be displayed in the changelog. If you need |
| 217 | to specify other details, you can use the commit body, but it won't be visible. |
| 218 | |
| 219 | Formatting tricks: the commit subject may contain: |
| 220 | |
| 221 | - Links to related issues or PRs by writing `#issue`. This will be highlighted by the changelog tool: |
| 222 | ``` |
| 223 | feat(archlinux): add support for aura AUR helper (#9467) |
| 224 | ``` |
| 225 | |
| 226 | - Formatted inline code by using backticks: the text between backticks will also be highlighted by |
| 227 | the changelog tool: |
| 228 | ``` |
| 229 | feat(shell-proxy): enable unexported `DEFAULT_PROXY` setting (#9774) |
| 230 | ``` |
| 231 | |
| 232 | ### Style |
| 233 | |
| 234 | Try to keep the first commit line short. It's harder to do using this commit style but try to be |
| 235 | concise, and if you need more space, you can use the commit body. Try to make sure that the commit |
| 236 | subject is clear and precise enough that users will know what changed by just looking at the changelog. |
| 237 | |
| 238 | ---- |
| 239 | |
| 240 | ## Volunteer |
| 241 | |
| 242 | Very nice!! :) |
| 243 | |
| 244 | Please have a look at the [Volunteer](https://github.com/ohmyzsh/ohmyzsh/wiki/Volunteers) |
| 245 | page for instructions on where to start and more. |