mirror of
https://github.com/ohmybash/oh-my-bash.git
synced 2024-09-21 10:27:09 +00:00
218 lines
9.0 KiB
Markdown
218 lines
9.0 KiB
Markdown
# CONTRIBUTING GUIDELINES
|
|
|
|
Oh-My-Bash is a community-driven project. Contribution is welcome, encouraged and appreciated.
|
|
It is also essential for the development of the project.
|
|
|
|
These guidelines are an attempt at better addressing the huge amount of pending
|
|
issues and pull requests. Please read them closely.
|
|
|
|
Foremost, be so kind as to [search](#use-the-search-luke). This ensures any contribution
|
|
you would make is not already covered.
|
|
|
|
* [Issues](#reporting-issues)
|
|
* [You have a problem](#you-have-a-problem)
|
|
* [You have a suggestion](#you-have-a-suggestion)
|
|
* [Pull Requests](#pull-requests)
|
|
* [Getting started](#getting-started)
|
|
* [You have a solution](#you-have-a-solution)
|
|
* [New Theme](#new-theme)
|
|
* [New Plugin](#new-plugin)
|
|
* [Copyright and responsibility](#copyright-and-responsibility)
|
|
* [Improving PR](#improving-pr)
|
|
* [Information sources (_aka_ search)](#use-the-search-luke)
|
|
|
|
**BONUS:** [Volunteering](#you-have-spare-time-to-volunteer)
|
|
|
|
## Reporting Issues
|
|
|
|
### You have a problem
|
|
|
|
Please be so kind as to [search](#use-the-search-luke) for any open issue already covering
|
|
your problem.
|
|
|
|
If you find one, comment on it so we can know there are more people experiencing it.
|
|
|
|
If not, look at the [Troubleshooting](https://github.com/ohmybash/oh-my-bash/wiki/Troubleshooting)
|
|
page for instructions on how to gather data to better debug your problem.
|
|
|
|
Then, you can go ahead and create an issue with as much detail as you can provide.
|
|
It should include the data gathered as indicated above, along with:
|
|
|
|
1. How to reproduce the problem
|
|
2. What the correct behavior should be
|
|
3. What the actual behavior is
|
|
|
|
Please copy to anyone relevant (e.g. plugin maintainers) by mentioning their GitHub handle
|
|
(starting with `@`) in your message.
|
|
|
|
We will do our very best to help you.
|
|
|
|
### You have a suggestion
|
|
|
|
Please be so kind as to [search](#use-the-search-luke) for any open issue already covering
|
|
your suggestion.
|
|
|
|
If you find one, comment on it so we can know there are more people supporting it.
|
|
|
|
If not, you can go ahead and create an issue. Please copy to anyone relevant (_eg_ plugin
|
|
maintainers) by mentioning their GitHub handle (starting with `@`) in your message.
|
|
|
|
## Pull Requests
|
|
|
|
The code should work with Bash 3.2. Make all the changes to be
|
|
POSIX-compatible for external tools unless it is related to a plugin that
|
|
clearly targets specific tools or environment such as "GNU make" or "macOS".
|
|
|
|
### Getting started
|
|
|
|
Before starting to work on it, please be so kind as to
|
|
[search](#use-the-search-luke) for any open issues, and any
|
|
pending/merged/rejected PRs covering or related to what you are going to
|
|
change.
|
|
|
|
- If you try to solve a [problem](#you-have-a-problem) and a solution to the
|
|
problem is already reported, try it out and +1 the pull request if the
|
|
solution works OK. On the other hand, if you think your solution is better,
|
|
post it with a reference to the other one so we can have both solutions to
|
|
compare.
|
|
- If you find an existing PR that is related, try it out and work with the
|
|
author on a common solution.
|
|
- If not, then go ahead and submit a PR. Please copy to anyone relevant
|
|
(e.g. plugin maintainers) by mentioning their GitHub handle (starting with
|
|
`@`) in your message.
|
|
|
|
You should be familiar with the basics of
|
|
[contributing on GitHub](https://help.github.com/articles/using-pull-requests) and have a fork
|
|
[properly set up](https://github.com/ohmybash/oh-my-bash/wiki/Contribution-Technical-Practices).
|
|
|
|
You MUST always create a PR with _a dedicated branch_ (i.e., a branch that is
|
|
NOT `master`) based on the latest upstream tree.
|
|
|
|
The commit message typically has the following form (with the first word in the
|
|
verbal phrase being in the infinitive and capitalized):
|
|
|
|
```
|
|
<section>: <Verb phrase to describe the change>
|
|
|
|
<detailed description if any>
|
|
```
|
|
|
|
The conventional commits are also accepted:
|
|
|
|
```
|
|
<type>(<section>): <verb phrase to describe the change>
|
|
|
|
<detailed description if any>
|
|
```
|
|
|
|
When you open a new PR, please make sure you do it right. Also, reference in
|
|
the PR description body any issues that would be solved by the PR, [for
|
|
instance](https://help.github.com/articles/closing-issues-via-commit-messages/)
|
|
_"Fixes #XXXX"_ for issue number XXXX.
|
|
|
|
### You have a solution
|
|
|
|
If you try to fix a problem or solve an issue in a specific
|
|
plugin/theme/aliases, please also check the other modules if they have a
|
|
similar issue or can be improved in a similar way.
|
|
|
|
### New Theme
|
|
|
|
A new theme is often created by modifying an existing theme. In that case,
|
|
please clarify from which theme the new theme is derived from. If possible, it
|
|
is recommended to source the original theme file
|
|
`"$OSH"/themes/<original>/<original>.base.sh` or
|
|
`"$OSH"/themes/<original>/<original>.theme.sh` in the new theme file
|
|
`"$OSH"/themes/<new>/<new>.theme.sh` and include only the new parts in the new
|
|
theme file.
|
|
|
|
The theme needs to have exactly one image file. The image size needs to be
|
|
height ~290px and width 600..800px to make the theme gallery aligned and also
|
|
to keep the repository size small. The filename should be `<theme
|
|
name>-dark.png` or `<theme name>-light.png` depending on the dark or light
|
|
background of the terminal used to make the image.
|
|
|
|
When you add a new theme, please also update
|
|
[themes/THEMES.md](https://github.com/ohmybash/oh-my-bash/blob/master/themes/THEMES.md).
|
|
After your new theme is merged, the list in
|
|
[Themes](https://github.com/ohmybash/oh-my-bash/wiki/Themes) in the wiki also
|
|
needs to be updated.
|
|
|
|
### New Plugin
|
|
|
|
A new plugin is accepted when it is needed to implement features in themes or
|
|
when it provides significantly useful tools for interactive uses. To show that
|
|
it is worth including in Oh My Bash, you will have to find testers to +1 your
|
|
PR.
|
|
|
|
When you add a new plugin, please also update
|
|
[plugins/README.md](https://github.com/ohmybash/oh-my-bash/blob/master/plugins/README.md)
|
|
|
|
### Copyright and responsibility
|
|
|
|
If you submit codes derived from other's work, please confirm that the license
|
|
is compatible with the MIT license. Please clarify which part is your own work
|
|
and which is not in the code and include **the copyright notice of the original
|
|
authors**. You may also include your own copyright notice, but we may omit
|
|
them because we can track them in the Git history.
|
|
|
|
You can provide codes under any licenses which are compatible with the MIT
|
|
license. When you submit and update a PR (*NOT when the PR is merged*), unless
|
|
otherwise specified, **we assume that you provide the codes/texts under the MIT
|
|
license**. If you would like to provide the codes/texts with another license,
|
|
please specify it in the codes/texts. If you forgot to declare the license
|
|
that is not MIT, you can later declare it for the part you contributed.
|
|
|
|
Do not submit AI-generated codes/documentation unless you understand both the
|
|
generated codes/documentation and the related **exiting codebase**. You are
|
|
required to be responsible for requests to the changes and reports of the
|
|
issues for the submitted codes/documentation. Also, please confirm that the
|
|
generated codes/texts can be included in Oh My Bash **with your own copyright
|
|
under the MIT license**.
|
|
|
|
### Improving PR
|
|
|
|
After opening PRs, you will usually receive requests for changes. It is rare
|
|
for a PR to be merged without any modifications. Please be so kind as to
|
|
respond to the requests. If you have any questions, please feel free to ask
|
|
further. If you become busy, please tell us that instead of ignoring our
|
|
messages. You are expected to notify when you will be available again, hand
|
|
over the PR to others, or to notify that you would discard the PR.
|
|
|
|
After the final version of the PR is settled, the fix-up commits that fix
|
|
problems introduced in earlier commits in the same PR will be squashed. Also,
|
|
the commits whose purposes heavily overlap will be squashed.
|
|
|
|
For this reason, a weight of one commit is not equal for different types of
|
|
contributions. For the new theme/plugin/aliases, the PR is likely to be
|
|
squashed into a single commit unless the changes are properly separated into
|
|
commits for respective purposes. On the other hand, PRs including several
|
|
minor fixes to the exiting codebase will not be squashed because each commit
|
|
gives a separate fix to the exiting code.
|
|
|
|
----
|
|
|
|
## Use the Search, Luke
|
|
|
|
_May the Force (of past experiences) be with you_
|
|
|
|
GitHub offers [many search features](https://help.github.com/articles/searching-github/)
|
|
to help you check whether a similar contribution to yours already exists. Please search
|
|
before making any contribution, it avoids duplicates and eases maintenance. Trust me,
|
|
that works 90% of the time.
|
|
|
|
You can also take a look at the [FAQ](https://github.com/ohmybash/oh-my-bash/wiki/FAQ)
|
|
to be sure your contribution has not already come up.
|
|
|
|
If all fails, your thing has probably not been reported yet, so you can go ahead
|
|
and [create an issue](#reporting-issues) or [submit a PR](#submitting-pull-requests).
|
|
|
|
----
|
|
|
|
### You have spare time to volunteer
|
|
|
|
Very nice!! :)
|
|
|
|
Please have a look at the [Volunteer](https://github.com/ohmybash/oh-my-bash/wiki/Volunteers)
|
|
page for instructions on where to start and more.
|