180 lines
6.3 KiB
Markdown
180 lines
6.3 KiB
Markdown
|
# Contributing to jsGanttImproved
|
||
|
|
||
|
We'd love for you to contribute to our source code and to make jsGanttImproved even better than it is
|
||
|
today! Here are the guidelines we'd like you to follow:
|
||
|
|
||
|
- [Issues and Bugs](#issue)
|
||
|
- [Feature Requests](#feature)
|
||
|
- [Submission Guidelines](#submit)
|
||
|
- [Coding Rules](#rules)
|
||
|
- [Commit Message Guidelines](#commit)
|
||
|
- [Further Info](#info)
|
||
|
|
||
|
## <a name="issue"></a> Found an Issue?
|
||
|
|
||
|
If you find a bug in the source code or a mistake in the documentation, you can help us by
|
||
|
submitting an issue to our [GitHub Repository][github]. Even better you can submit a Pull Request
|
||
|
with a fix.
|
||
|
|
||
|
**Please see the [Submission Guidelines](#submit) below.**
|
||
|
|
||
|
## <a name="feature"></a> Want a Feature?
|
||
|
|
||
|
You can request a new feature by submitting an issue to our [GitHub Repository][github]. If you
|
||
|
would like to implement a new feature then it can be crafted and submitted as a Pull Request.
|
||
|
|
||
|
## <a name="submit"></a> Submission Guidelines
|
||
|
|
||
|
### Submitting an Issue
|
||
|
Before you submit your issue search the archive, maybe your question was already answered.
|
||
|
|
||
|
If your issue appears to be a bug, and hasn't been reported, open a new issue. Help us to maximize
|
||
|
the effort we can spend fixing issues and adding new features, by not reporting duplicate issues.
|
||
|
Providing the following information will increase the chances of your issue being dealt with
|
||
|
quickly:
|
||
|
|
||
|
* **Overview of the Issue** - if an error is being thrown a non-minified stack trace helps
|
||
|
* **Motivation for or Use Case** - explain why this is a bug for you
|
||
|
* **Version(s)** - what is the version(s) being used?
|
||
|
* **Browsers and Operating System** - is this a problem with all browsers or only specific ones?
|
||
|
* **Reproduce the Error** - provide a live example (using [Plunker][plunker] or
|
||
|
[JSFiddle][jsfiddle]) or an unambiguous set of steps.
|
||
|
* **Related Issues** - has a similar issue been reported before?
|
||
|
* **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might be
|
||
|
causing the problem (line of code or commit)
|
||
|
|
||
|
### Submitting a Pull Request
|
||
|
Before you submit your pull request consider the following guidelines:
|
||
|
|
||
|
* Search [GitHub](https://github.com/jsGanttImproved/jsgantt-improved/pulls) for an open or closed Pull Request
|
||
|
that relates to your submission. You don't want to duplicate effort.
|
||
|
* Make your changes in a new git branch:
|
||
|
|
||
|
```shell
|
||
|
git checkout -b my-fix-branch master
|
||
|
```
|
||
|
|
||
|
* Create your patch.
|
||
|
* Follow our [Coding Rules](#rules).
|
||
|
* Commit your changes using a descriptive commit message that follows our
|
||
|
[commit message conventions](#commit).
|
||
|
|
||
|
```shell
|
||
|
git commit -a
|
||
|
```
|
||
|
Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files.
|
||
|
|
||
|
* Push your branch to GitHub:
|
||
|
|
||
|
```shell
|
||
|
git push origin my-fix-branch
|
||
|
```
|
||
|
|
||
|
In GitHub, send a pull request to `master`.
|
||
|
If we suggest changes, then:
|
||
|
|
||
|
* Make the required updates.
|
||
|
* Commit your changes to your branch (e.g. `my-fix-branch`).
|
||
|
* Push the changes to your GitHub repository (this will update your Pull Request).
|
||
|
|
||
|
If the PR gets too outdated we may ask you to rebase and force push to update the PR:
|
||
|
|
||
|
```shell
|
||
|
git rebase master -i
|
||
|
git push origin my-fix-branch -f
|
||
|
```
|
||
|
|
||
|
_WARNING: Squashing or reverting commits and force-pushing thereafter may remove GitHub comments
|
||
|
on code that were previously made by you or others in your commits. Avoid any form of rebasing
|
||
|
unless necessary._
|
||
|
|
||
|
That's it! Thank you for your contribution!
|
||
|
|
||
|
#### After your pull request is merged
|
||
|
|
||
|
After your pull request is merged, you can safely delete your branch and pull the changes
|
||
|
from the main (upstream) repository:
|
||
|
|
||
|
* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:
|
||
|
|
||
|
```shell
|
||
|
git push origin --delete my-fix-branch
|
||
|
```
|
||
|
|
||
|
* Check out the master branch:
|
||
|
|
||
|
```shell
|
||
|
git checkout master -f
|
||
|
```
|
||
|
|
||
|
* Delete the local branch:
|
||
|
|
||
|
```shell
|
||
|
git branch -D my-fix-branch
|
||
|
```
|
||
|
|
||
|
* Update your master with the latest upstream version:
|
||
|
|
||
|
```shell
|
||
|
git pull --ff upstream master
|
||
|
```
|
||
|
|
||
|
## <a name="rules"></a> Coding Rules
|
||
|
|
||
|
To ensure consistency throughout the source code, keep these rules in mind as you are working:
|
||
|
|
||
|
* With the exceptions listed below, we follow the rules contained in
|
||
|
[Google's JavaScript Style Guide][js-style-guide]:
|
||
|
* Wrap all code at **100 characters**.
|
||
|
|
||
|
## <a name="commit"></a> Git Commit Guidelines
|
||
|
|
||
|
We have very precise rules over how our git commit messages can be formatted. This leads to **more
|
||
|
readable messages** that are easy to follow when looking through the **project history**.
|
||
|
|
||
|
### Commit Message Format
|
||
|
Each commit message consists of a **subject**, a **body** and a **footer**:
|
||
|
|
||
|
```
|
||
|
<subject>
|
||
|
<BLANK LINE>
|
||
|
<body>
|
||
|
<BLANK LINE>
|
||
|
<footer>
|
||
|
```
|
||
|
|
||
|
The **subject** is mandatory.
|
||
|
|
||
|
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier
|
||
|
to read on GitHub as well as in various git tools.
|
||
|
|
||
|
### Revert
|
||
|
If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit.
|
||
|
In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit being reverted.
|
||
|
|
||
|
### Subject
|
||
|
The subject contains succinct description of the change:
|
||
|
|
||
|
* use the imperative, present tense: "change" not "changed" nor "changes"
|
||
|
* don't capitalize first letter
|
||
|
* no dot (.) at the end
|
||
|
|
||
|
### Body
|
||
|
Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes".
|
||
|
The body should include the motivation for the change and contrast this with previous behavior.
|
||
|
|
||
|
### Footer
|
||
|
The footer should contain any information about **Breaking Changes** and is also the place to
|
||
|
[reference GitHub issues that this commit closes][closing-issues].
|
||
|
|
||
|
**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines.
|
||
|
The rest of the commit message is then used for this.
|
||
|
|
||
|
## <a name="info"></a> Further Information
|
||
|
You can find out more detailed information about contributing in the [Documentation][docs].
|
||
|
|
||
|
|
||
|
[github]: https://github.com/jsGanttImproved/jsgantt-improved
|
||
|
[js-style-guide]: https://google.github.io/styleguide/jsguide.html
|
||
|
[closing-issues]: https://help.github.com/articles/closing-issues-via-commit-messages/
|
||
|
[docs]: https://github.com/jsGanttImproved/jsgantt-improved/wiki/Documentation
|