From 26e73313cf1c4e26d687c804cf8c7fff0c33a1b0 Mon Sep 17 00:00:00 2001 From: Rob Frawley 2nd Date: Fri, 2 Mar 2018 21:09:43 -0500 Subject: [PATCH] add code of conduct, update contributing instructions, and include conduct note in readme --- CODE_OF_CONDUCT.md | 76 ++++++++++++++ CONTRIBUTING.md | 246 ++++++++++++++++++++++++++++++--------------- README.md | 4 + 3 files changed, 243 insertions(+), 83 deletions(-) create mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..2f02fd8b0 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c52f2aba2..ca3b0316e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 with your github username) + git clone git@github.com:/LiipImagineBundle.git + + # enter the newly cloned repository directory + cd LiipImagineBunde + + # EITHER checkout a "feature-" branch if creating a new feature + git checkout -b feature-name-of-addition + + # OR checkout a "bugfix-" 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 diff --git a/README.md b/README.md index 164e3fd96..2b389b599 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,10 @@ filter. ``` +### Contributor Code of Conduct + +This project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). +By participating in this project you agree to abide by its terms. ### Attribution