stow/oh-my-zsh/.oh-my-zsh/CONTRIBUTING.md

   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 can know there are more people 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:
  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 can know there are more people 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 a 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're requiring 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 there exists a command with the same name, 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. This is 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.