diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..fa7e0998 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,228 @@ +# Contributing to ng2-admin + +We would love for you to contribute to ng2-admin and help make it even better than it is +today! As a contributor, here are the guidelines we would like you to follow: + + - [Question or Problem?](#question) + - [Issues and Bugs](#issue) + - [Feature Requests](#feature) + - [Submission Guidelines](#submit) + - [Commit Message Guidelines](#commit) + +## Got a Question or Problem? + +Please, do not open issues for the general support questions as we want to keep GitHub issues for bug reports and feature requests. + +StackOverflow is a much better place to ask questions since: + +- there are thousands of people willing to help on StackOverflow +- questions and answers stay available for public viewing so your question / answer might help someone else +- StackOverflow's voting system assures that the best answers are prominently visible. + +To save your and our time we will be systematically closing all the issues that are requests for general support and redirecting people to StackOverflow. + +If you would like to chat about the question in real-time, you can reach out via [our gitter channel][gitter]. + +## Found a Bug? +If you find a bug in the source code, you can help us by +[submitting an issue](#submit-issue) to our [GitHub Repository][github]. Even better, you can +[submit a Pull Request](#submit-pr) with a fix. + +## Missing a Feature? +You can *request* a new feature by [submitting an issue](#submit-issue) to our GitHub +Repository. If you would like to *implement* a new feature, please submit an issue with +a proposal for your work first, to be sure that we can use it. +Please consider what kind of change it is: + +* For a **Major Feature**, first open an issue and outline your proposal so that it can be +discussed. This will also allow us to better coordinate our efforts, prevent duplication of work, +and help you to craft the change so that it is successfully accepted into the project. +* **Small Features** can be crafted and directly [submitted as a Pull Request](#submit-pr). + +## Submission Guidelines + +### Submitting an Issue + +Before you submit an issue, please search the issue tracker, maybe an issue for your problem already exists and the discussion might inform you of workarounds readily available. + +We want to fix all the issues as soon as possible, but before fixing a bug we need to reproduce and confirm it. In order to reproduce bugs we will systematically ask you to provide a minimal reproduction scenario using http://plnkr.co. Having a live, reproducible scenario gives us wealth of important information without going back & forth to you with additional questions like: + +- version of ng2-admin used +- 3rd-party libraries and their versions +- and most importantly - a use-case that fails + +A minimal reproduce scenario using http://plnkr.co/ allows us to quickly confirm a bug (or point out coding problem) as well as confirm that we are fixing the right problem. If plunker is not a suitable way to demonstrate the problem (for example for issues related to our npm packaging), please create a standalone git repository demonstrating the problem. + +We will be insisting on a minimal reproduce scenario in order to save maintainers time and ultimately be able to fix more bugs. Interestingly, from our experience users often find coding problems themselves while preparing a minimal plunk. We understand that sometimes it might be hard to extract essentials bits of code from a larger code-base but we really need to isolate the problem before we can fix it. + +Unfortunately we are not able to investigate / fix bugs without a minimal reproduction, so if we don't hear back from you we are going to close an issue that don't have enough info to be reproduced. + +You can file new issues by filling out our [new issue form](https://github.com/akveo/ng2-admin/issues/new). + + +### Submitting a Pull Request (PR) +Before you submit your Pull Request (PR) consider the following guidelines: + +* Search [GitHub](https://github.com/akveo/ng2-admin/pulls) for an open or closed PR + 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 + ``` + +* Commit your changes using a descriptive commit message that follows our + [commit message conventions](#commit). Adherence to these conventions + is necessary because release notes are automatically generated from these messages. + + ```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 `ng2-admin:master`. +* If we suggest changes then: + * Make the required updates. + * Rebase your branch and force push to your GitHub repository (this will update your Pull Request): + + ```shell + git rebase master -i + git push -f + ``` + +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 + ``` + +## Commit Message 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**. But also, +we use the git commit messages to **generate the ng2-admin change log**. + +### Commit Message Format +Each commit message consists of a **header**, a **body** and a **footer**. The header has a special +format that includes a **type**, a **scope** and a **subject**: + +``` +(): + + + +