Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1071 from robfrawley/feature-add-code-of-conduct
[Meta] Add code of conduct and update contributor instructions
- Loading branch information
Showing
3 changed files
with
243 additions
and
83 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
|
|
||
| # Contributor Covenant Code of Conduct | ||
|
|
||
| ## Our Pledge | ||
|
|
||
| In the interest of fostering an open and welcoming environment, we as | ||
| contributors and maintainers pledge to making participation in our project and | ||
| our community a harassment-free experience for everyone, regardless of age, body | ||
| size, disability, ethnicity, gender identity and expression, level of experience, | ||
| education, socio-economic status, nationality, personal appearance, race, | ||
| religion, or sexual identity and orientation. | ||
|
|
||
| ## Our Standards | ||
|
|
||
| Examples of behavior that contributes to creating a positive environment | ||
| include: | ||
|
|
||
| * Using welcoming and inclusive language | ||
| * Being respectful of differing viewpoints and experiences | ||
| * Gracefully accepting constructive criticism | ||
| * Focusing on what is best for the community | ||
| * Showing empathy towards other community members | ||
|
|
||
| Examples of unacceptable behavior by participants include: | ||
|
|
||
| * The use of sexualized language or imagery and unwelcome sexual attention or | ||
| advances | ||
| * Trolling, insulting/derogatory comments, and personal or political attacks | ||
| * Public or private harassment | ||
| * Publishing others' private information, such as a physical or electronic | ||
| address, without explicit permission | ||
| * Other conduct which could reasonably be considered inappropriate in a | ||
| professional setting | ||
|
|
||
| ## Our Responsibilities | ||
|
|
||
| Project maintainers are responsible for clarifying the standards of acceptable | ||
| behavior and are expected to take appropriate and fair corrective action in | ||
| response to any instances of unacceptable behavior. | ||
|
|
||
| Project maintainers have the right and responsibility to remove, edit, or | ||
| reject comments, commits, code, wiki edits, issues, and other contributions | ||
| that are not aligned to this Code of Conduct, or to ban temporarily or | ||
| permanently any contributor for other behaviors that they deem inappropriate, | ||
| threatening, offensive, or harmful. | ||
|
|
||
| ## Scope | ||
|
|
||
| This Code of Conduct applies both within project spaces and in public spaces | ||
| when an individual is representing the project or its community. Examples of | ||
| representing a project or community include using an official project e-mail | ||
| address, posting via an official social media account, or acting as an appointed | ||
| representative at an online or offline event. Representation of a project may be | ||
| further defined and clarified by project maintainers. | ||
|
|
||
| ## Enforcement | ||
|
|
||
| Instances of abusive, harassing, or otherwise unacceptable behavior may be | ||
| reported by contacting the project team at __imagine-bundle@googlegroups.com__. All | ||
| complaints will be reviewed and investigated and will result in a response that | ||
| is deemed necessary and appropriate to the circumstances. The project team is | ||
| obligated to maintain confidentiality with regard to the reporter of an incident. | ||
| Further details of specific enforcement policies may be posted separately. | ||
|
|
||
| Project maintainers who do not follow or enforce the Code of Conduct in good | ||
| faith may face temporary or permanent repercussions as determined by other | ||
| members of the project's leadership. | ||
|
|
||
| ## Attribution | ||
|
|
||
| This Code of Conduct is adapted from the [Contributor Covenant][coc-home], | ||
| [version 1.4][coc-14], available at | ||
| [contributor-covenant.org/version/1/4/code-of-conduct.html][coc-14]. | ||
|
|
||
| [coc-home]: https://www.contributor-covenant.org | ||
| [coc-14]: https://www.contributor-covenant.org/version/1/4/code-of-conduct.html |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,97 +1,177 @@ | ||
| Contribution Guidelines | ||
| ======================= | ||
|
|
||
| First of all, each single contribution is appreciated, whether a typo fix, | ||
| improved documentation, a fixed bug or a whole new feature. | ||
| # Contributing | ||
|
|
||
| ## Feature request | ||
| This project is released with a [Contributor Code of Conduct][coc-md]. By participating in | ||
| this project you agree to abide by its terms. | ||
|
|
||
| If you think a feature is missing, please report it or implement it. If you report it, describe | ||
| precisely what you would like to see implemented. It would be nice if you can do | ||
| some search before submitting it and link the resources to your description. | ||
| ## Request Feature | ||
|
|
||
| ## Bug report | ||
| If you believe a feature is missing, report it by [creating a new issue][issue-make] or | ||
| implement it by [submitting a pull request][pr-make]. | ||
|
|
||
| If you think you have detected a bug or a doc issue, please report it (open [issue][issue]) or even better fix it. If you report it, | ||
| please be the more precise possible. Here a little list of required information: | ||
| *If you __request__ a new feature*, describe precisely what you would like implemented and | ||
| be sure to completely and accurately fill out the new issue template by providing the | ||
| *branch you would like the feature implemented on*, whether the feature *breaks backwards | ||
| compatibility*, and *any other requested details*. Moreover, including a detailed | ||
| description, links to external resources, and other references will provide guidance and | ||
| context for whomever ultimately implementations your request. | ||
|
|
||
| * Symfony-standard fork which reproduces the bug. | ||
| * Precise description of the bug. | ||
| * Symfony version used. | ||
| * Bundle version used. | ||
| *If you __submit__ a new feature*, ensure you provide a verbose description of your | ||
| contribution, again making sure to completely fill out the new pull request template. Your | ||
| pull request must pass our [Travis automated build check][travis], which runs our unit test | ||
| suite against various PHP versions and checks that proper code style standards are met. | ||
|
|
||
| ## Report Bug | ||
|
|
||
| If you believe you have encountered a *behavioral bug*, *documentation error*, or *other | ||
| issue*, first search for an [existing issue][issue-list], and if one does't already exist, | ||
| then proceed to [create a new issue][issue-make]. If you have the available time and the | ||
| required skill set, we appreciate those who offer fixes themselves via | ||
| [pull requests][pr-list], as well. | ||
|
|
||
| ## Bug fix | ||
|
|
||
| Fork the repository, clone it and create a new branch with the following commands: | ||
|
|
||
| ``` bash | ||
| $ git clone git@github.com:liip/LiipImagineBundle.git | ||
| $ git checkout -b bug-fix-description | ||
| ``` | ||
|
|
||
| Then, install the dependencies through [Composer][composer] | ||
|
|
||
| ``` bash | ||
| $ composer install | ||
| ``` | ||
|
|
||
| When you're on the new branch with the dependencies, code as much as you want and when the fix is ready, | ||
| you will need to add tests and update the documentation. Everything is tested with | ||
| [PHPUnit][php-unit], documentation formatted with [reStructuredText][rst] under the `Resources/doc` directory. | ||
|
|
||
| To run tests, use the following command: | ||
|
|
||
| ``` bash | ||
| $ ./bin/phpunit | ||
| ``` | ||
|
|
||
| ## Making your changes | ||
|
|
||
| 1. Fork the repository on GitHub | ||
| 2. Pull requests must be sent from a new hotfix/feature branch, not from `master`. | ||
| 3. Make your modifications, coding standard for the project is [PSR-2][PSR-2] | ||
| 4. Commit small logical changes, each with a descriptive commit message. | ||
| Please don't mix unrelated changes in a single commit. | ||
|
|
||
| ## Commit messages | ||
|
|
||
| Please format your commit messages as follows: | ||
|
|
||
| Short summary of the change (up to 50 characters) | ||
| Be sure to complete the new issue template by providing the *version of the bundle used*, | ||
| the *version of Symfony used*, and *any other requested information*. It is also helpful | ||
| to create a Symfony-standard fork reproducing the unexpected behavior; this provides those | ||
| trying to assist you with a working example of the bug. The more detail you provide the | ||
| more likely the issue will meet a beneficial resolution. | ||
|
|
||
| ## Submit Your Changes | ||
|
|
||
| Whether you are creating a __bug fix__ or a __new feature__, the workflow for forking the | ||
| bundle, working on local changes, and finally requesting that your changes are merged back | ||
| into the upstream repository is the same. | ||
|
|
||
| 1. __Fork/Clone/Branch Repository:__ | ||
| Fork the repository using the [GitHub][gh] web interface, clone your fork, and create a | ||
| local `feature-` branch for new features or `bugfix-` branch for bug fixes. | ||
|
|
||
| ```bash | ||
| # after forking, clone your fork (replace <user> with your github username) | ||
| git clone git@github.com:<user>/LiipImagineBundle.git | ||
|
|
||
| # enter the newly cloned repository directory | ||
| cd LiipImagineBunde | ||
|
|
||
| # EITHER checkout a "feature-<name>" branch if creating a new feature | ||
| git checkout -b feature-name-of-addition | ||
|
|
||
| # OR checkout a "bugfix-<name>" branch if working on a bug fix | ||
| git checkout -b bugfix-name-of-issue | ||
| ``` | ||
|
|
||
| 2. __Install Dependencies:__ | ||
| Install the project's dependencies using [Composer][composer]. You *may* also install any | ||
| of the optional dependencies defined in this project's [composer.json file][composer-file], | ||
| such as the [mongo php adapter][mongo-php] or the [monolog library][monolog], depending on | ||
| the features required. | ||
|
|
||
| ```bash | ||
| # install required, default dependencies | ||
| composer install | ||
|
|
||
| # install any optional dependencies, if required | ||
| composer require namespace/package | ||
| ``` | ||
|
|
||
| *Note: For instructions on installing [Composer][composer], reference their | ||
| official [download instructions][composer-dl].* | ||
|
|
||
| 3. __Work/Stage/Commit (Repeat):__ | ||
| Make the code changes required to fix your bug or implement your new feature, then stage | ||
| your files with `git add` and commit your work with `git commit`. Your commit messages | ||
| should summarize the changes such that others can gain a general understanding of both | ||
| your literal changes and general intentions. | ||
|
|
||
| ```bash | ||
| # stage your changed files or directories | ||
| git add foo/bar/file-a.ext | ||
|
|
||
| # commit your changes with a short descriptive message | ||
| git commit -m 'changed a, b, and c to implement d' | ||
| ``` | ||
|
|
||
| *Note: It is highly recommended that you create frequent, small commits instead of large, | ||
| unorganized ones. While smaller commits are easier to review and track for the project, | ||
| they also allow you to easily revert local work if your progress detours down unproductive | ||
| path.* | ||
|
|
||
| 4. __Add/Edit Unit Tests:__ | ||
| You *must* add tests, as appropriate for the changes and/or additions you've made to the | ||
| project. This project's test suite uses [PHPUnit][php-unit] and the unit tests can be | ||
| found in the `Tests/` directory. | ||
|
|
||
| ```bash | ||
| # run the test suite by calling simple-phpunit | ||
| vendor/bin/simple-phpunit | ||
| ``` | ||
|
|
||
| 5. __Add/Edit Documentation:__ | ||
| All user-facing changes must be properly reflected in our documentation, whether your | ||
| changes amend or add functionality. Documentation is formatted with | ||
| [reStructuredText (RST)][rst-info] and can be found in the `Resources/doc/` directory. | ||
| These [RST][rst-info] files are automatically compiled to generate our | ||
| [official documentation website][docs]. | ||
|
|
||
| *Note: To test your local documentation changes, reference the | ||
| [Building RST Documentation][rst-make] wiki page where you will find detailed | ||
| information on compiling the documentation on your local environment.* | ||
|
|
||
| 6. __Apply Code Style Standards:__ | ||
| You *must* ensure your changes abide by our code style standards before submitting any | ||
| changes. To facilitate this, we define a [code style configuration file][cs-conf] for | ||
| [php-cs-fixer][cs] that enabled you to apply our require code style in an automated | ||
| manner. | ||
|
|
||
| ```bash | ||
| # call php-cs-fixer with "--dry-run" option to view changes without applying them | ||
| vendor/bin/php-cs-fixer fix -vvv --diff --dry-run | ||
|
|
||
| # to apply the code style changes, run without the "--dry-run" option | ||
| vendor/bin/php-cs-fixer fix -vvv --diff | ||
|
|
||
| # commit any changes made by the tool | ||
| git commit -a -m 'php-cs-fixer run' | ||
| ``` | ||
|
|
||
| Optionally add a more extensive description of your change after a | ||
| blank line. Wrap the lines in this and the following paragraphs after | ||
| 72 characters. | ||
| *Note: Our [automated Travis builds][travis] will mark a [pull request][pr-make] failed if | ||
| it does not meet the required code style standards.* | ||
|
|
||
| ## Submitting your changes | ||
| 7. __Push to Fork/Merge Upstream:__ | ||
| Having completed your local changes, added tests and documentation, and ensured code | ||
| style standards are met, push your local changes back to your personal [GitHub][gh] fork | ||
| of the repository. | ||
|
|
||
| 1. Push your changes to a topic branch in your fork of the repository. | ||
| 2. [Submit a pull request][pr] to the original repository. | ||
| Describe your changes as short as possible, but as detailed as needed for | ||
| others to get an overview of your modifications. | ||
| 3. If you have reworked you patch, please squash all your commits in a single one with the following commands (here, we | ||
| will assume you would like to squash 3 commits in a single one): | ||
| ```bash | ||
| # push your local changes to your remote fork | ||
| git push master -u origin | ||
| ``` | ||
|
|
||
| ``` bash | ||
| $ git rebase -i HEAD~3 | ||
| ``` | ||
| 4. If your branch conflicts with the master branch, you will need to rebase and repush it with the following commands: | ||
| Once you've pushed your changes to your fork, use the [GitHub][gh] web interface to | ||
| [submit a pull request][gh-help-pr]. | ||
|
|
||
| ``` bash | ||
| $ git remote add upstream git@github.com:liip/LiipImagineBundle.git | ||
| $ git pull --rebase upstream master | ||
| $ git push origin bug-fix-description -f | ||
| ``` | ||
| ## Further information | ||
| ## Additional information | ||
|
|
||
| * [General GitHub documentation][gh-help] | ||
| * [GitHub pull request documentation][gh-pr] | ||
|
|
||
| [rst]: http://symfony.com/doc/current/contributing/documentation/format.html#restructuredtext | ||
| [php-unit]: http://phpunit.de/ | ||
| [composer]: https://getcomposer.org/ | ||
| [gh-help]: https://help.github.com | ||
| [gh-pr]: https://help.github.com/send-pull-requests | ||
| [issue]: https://github.com/liip/LiipImagineBundle/issues/new | ||
| [pr]: https://github.com/liip/LiipImagineBundle/pull/new | ||
| [PSR-2]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md | ||
| * [GitHub pull request documentation][gh-help-pr] | ||
|
|
||
| [cs-conf]: .php_cs.dist | ||
| [cs]: http://cs.sensiolabs.org/ | ||
| [gh-help]: https://help.github.com | ||
| [gh-help-pr]: https://help.github.com/send-pull-requests | ||
| [gh]: https://github.com | ||
| [pr-list]: https://github.com/liip/LiipImagineBundle/pulls | ||
| [pr-make]: https://github.com/liip/LiipImagineBundle/pull/new | ||
| [issue-list]: https://github.com/liip/LiipImagineBundle/issues | ||
| [issue-make]: https://github.com/liip/LiipImagineBundle/issues/new | ||
| [travis]: https://travis-ci.org/liip/LiipImagineBundle | ||
| [rst-info]: http://symfony.com/doc/current/contributing/documentation/format.html#restructuredtext | ||
| [rst-make]: https://github.com/liip/LiipImagineBundle/wiki/Building-RST-Documentation | ||
| [php-unit]: http://phpunit.de/ | ||
| [composer-file]: composer.json | ||
| [composer]: https://getcomposer.org/ | ||
| [composer-dl]: https://getcomposer.org/download/ | ||
| [coc-14]: https://www.contributor-covenant.org/version/1/4/code-of-conduct.html | ||
| [coc-md]: CODE_OF_CONDUCT.md | ||
| [docs]: https://symfony.com/doc/master/bundles/LiipImagineBundle/index.html | ||
| [mongo-php]: https://github.com/alcaeus/mongo-php-adapter | ||
| [monolog]: https://github.com/Seldaek/monolog |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters