From 70db3d5f6360e5764a8948576ebdd12c2e74d192 Mon Sep 17 00:00:00 2001 From: Matthew Weier O'Phinney Date: Tue, 17 Apr 2018 11:20:36 -0500 Subject: [PATCH] Modernizes repository - Renames LICENSE.txt to LICENSE.md, and sets appropriate copyright range. - Adds issue and PR templates. - Adds code of conduct, contributing, and support guides. - Updates composer.json structure to match other components. --- .coveralls.yml | 2 + .gitattributes | 18 ++-- .gitignore | 11 +- .travis.yml | 2 +- LICENSE.txt => LICENSE.md | 18 ++-- README.md | 4 +- composer.json | 60 ++++++----- composer.lock | 2 +- docs/CODE_OF_CONDUCT.md | 43 ++++++++ docs/CONTRIBUTING.md | 189 ++++++++++++++++++++++++++++++++++ docs/ISSUE_TEMPLATE.md | 19 ++++ docs/PULL_REQUEST_TEMPLATE.md | 25 +++++ docs/SUPPORT.md | 25 +++++ 13 files changed, 364 insertions(+), 54 deletions(-) create mode 100644 .coveralls.yml rename LICENSE.txt => LICENSE.md (59%) create mode 100644 docs/CODE_OF_CONDUCT.md create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/ISSUE_TEMPLATE.md create mode 100644 docs/PULL_REQUEST_TEMPLATE.md create mode 100644 docs/SUPPORT.md diff --git a/.coveralls.yml b/.coveralls.yml new file mode 100644 index 0000000..bc71b62 --- /dev/null +++ b/.coveralls.yml @@ -0,0 +1,2 @@ +coverage_clover: clover.xml +json_path: coveralls-upload.json diff --git a/.gitattributes b/.gitattributes index 57607c1..6f9bfcf 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,9 +1,9 @@ -/doc export-ignore -/test export-ignore -/vendor export-ignore -.coveralls.yml export-ignore -.gitattributes export-ignore -.gitignore export-ignore -.travis.yml export-ignore -phpcs.xml export-ignore -phpunit.xml.dist export-ignore +/.coveralls.yml export-ignore +/.gitattributes export-ignore +/.gitignore export-ignore +/.travis.yml export-ignore +/composer.lock export-ignore +/docs/ export-ignore +/phpcs.xml export-ignore +/phpunit.xml.dist export-ignore +/test/ export-ignore diff --git a/.gitignore b/.gitignore index 9497d96..d822fd3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,4 @@ -nbproject -.idea -.buildpath -.project -.settings/ -.DS_Store -vendor/ +/clover.xml +/coveralls-upload.json +/phpunit.xml +/vendor/ diff --git a/.travis.yml b/.travis.yml index 6048d9f..45b5da2 100644 --- a/.travis.yml +++ b/.travis.yml @@ -65,4 +65,4 @@ install: script: - composer test - - if [[ $CS_CHECK == 'true' ]]; then composer cs ; fi + - if [[ $CS_CHECK == 'true' ]]; then composer cs-check ; fi diff --git a/LICENSE.txt b/LICENSE.md similarity index 59% rename from LICENSE.txt rename to LICENSE.md index 6eab5aa..9c36681 100644 --- a/LICENSE.txt +++ b/LICENSE.md @@ -1,19 +1,19 @@ -Copyright (c) 2005-2015, Zend Technologies USA, Inc. +Copyright (c) 2011-2018, Zend Technologies USA, Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - * Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. +- Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. +- Redistributions in binary form must reproduce the above copyright notice, this + list of conditions and the following disclaimer in the documentation and/or + other materials provided with the distribution. - * Neither the name of Zend Technologies USA, Inc. nor the names of its - contributors may be used to endorse or promote products derived from this - software without specific prior written permission. +- Neither the name of Zend Technologies USA, Inc. nor the names of its + contributors may be used to endorse or promote products derived from this + software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED diff --git a/README.md b/README.md index 1fe96ee..7e4be4a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # Zend Developer Tools -[![Build Status](https://travis-ci.org/zendframework/ZendDeveloperTools.svg)](https://travis-ci.org/zendframework/ZendDeveloperTools) +[![Build Status](https://secure.travis-ci.org/zendframework/ZendDeveloperTools.svg?branch=master)](https://secure.travis-ci.org/zendframework/ZendDeveloperTools) +[![Coverage Status](https://coveralls.io/repos/github/zendframework/ZendDeveloperTools/badge.svg?branch=master)](https://coveralls.io/github/zendframework/ZendDeveloperTools?branch=master) Module providing debug tools for use with [zend-mvc](https://docs.zendframework.com/zend-mvc) applications. @@ -17,6 +18,7 @@ Module providing debug tools for use with [zend-mvc](https://docs.zendframework. 2. Add the `ZendDeveloperTools` module to the module section of your `config/application.config.php`. Starting with version 1.1.0, if you are using [zend-component-installer](https://docs.zendframework.com/zend-component-installer), this will be done for you automatically. + 3. Copy `./vendor/zendframework/zend-developer-tools/config/zenddevelopertools.local.php.dist` to `./config/autoload/zenddevelopertools.local.php`. Change any settings in it according to your needs. diff --git a/composer.json b/composer.json index e8f7f1f..e564b25 100644 --- a/composer.json +++ b/composer.json @@ -1,34 +1,20 @@ { "name": "zendframework/zend-developer-tools", "description": "Module for developer and debug tools for use with zend-mvc applications.", - "type": "library", "license": "BSD-3-Clause", "keywords": [ + "zendframework", "debug", "developer", - "zf2", + "zf", "module" ], - "homepage": "https://github.com/zendframework/ZendDeveloperTools", - "authors": [ - { - "name": "Evan Coury", - "email": "me@evancoury.com", - "homepage": "http://blog.evan.pro/" - }, - { - "name": "Eric Boh", - "email": "cossish@gmail.com" - } - ], - "extra": { - "branch-alias": { - "dev-master": "1.1-dev", - "dev-develop": "1.2-dev" - }, - "zf": { - "module": "ZendDeveloperTools" - } + "support": { + "issues": "https://github.com/zendframework/ZendDeveloperTools/issues", + "source": "https://github.com/zendframework/ZendDeveloperTools", + "rss": "https://github.com/zendframework/ZendDeveloperTools/releases.atom", + "chat": "https://zendframework-slack.herokuapp.com", + "forum": "https://discourse.zendframework.com/c/questions/components" }, "require": { "php": "^5.6 || ^7.0", @@ -63,15 +49,37 @@ "ZendDeveloperToolsTest\\": "test/" } }, + "config": { + "sort-packages": true + }, + "extra": { + "branch-alias": { + "dev-master": "1.1.x-dev", + "dev-develop": "1.2.x-dev" + }, + "zf": { + "module": "ZendDeveloperTools" + } + }, "scripts": { "check": [ "@cs-check", "@test" ], - "coveralls": "coveralls", "cs-check": "phpcs", "cs-fix": "phpcbf", - "test": "phpunit", - "test-coverage": "phpunit --coverage-clover clover.xml" - } + "test": "phpunit --colors=always", + "test-coverage": "phpunit --colors=always --coverage-clover clover.xml" + }, + "authors": [ + { + "name": "Evan Coury", + "email": "me@evancoury.com", + "homepage": "http://blog.evan.pro/" + }, + { + "name": "Eric Boh", + "email": "cossish@gmail.com" + } + ] } diff --git a/composer.lock b/composer.lock index 1326fa7..cabcdfe 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "3d34b74e7d9a614de934e21d79e3c120", + "content-hash": "1f39d7319b4f10b2dbca529931800fa6", "packages": [ { "name": "container-interop/container-interop", diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..02fafcd --- /dev/null +++ b/docs/CODE_OF_CONDUCT.md @@ -0,0 +1,43 @@ +# Contributor Code of Conduct + +This project adheres to [The Code Manifesto](http://codemanifesto.com) +as its guidelines for contributor interactions. + +## The Code Manifesto + +We want to work in an ecosystem that empowers developers to reach their +potential — one that encourages growth and effective collaboration. A space that +is safe for all. + +A space such as this benefits everyone that participates in it. It encourages +new developers to enter our field. It is through discussion and collaboration +that we grow, and through growth that we improve. + +In the effort to create such a place, we hold to these values: + +1. **Discrimination limits us.** This includes discrimination on the basis of + race, gender, sexual orientation, gender identity, age, nationality, technology + and any other arbitrary exclusion of a group of people. +2. **Boundaries honor us.** Your comfort levels are not everyone’s comfort + levels. Remember that, and if brought to your attention, heed it. +3. **We are our biggest assets.** None of us were born masters of our trade. + Each of us has been helped along the way. Return that favor, when and where + you can. +4. **We are resources for the future.** As an extension of #3, share what you + know. Make yourself a resource to help those that come after you. +5. **Respect defines us.** Treat others as you wish to be treated. Make your + discussions, criticisms and debates from a position of respectfulness. Ask + yourself, is it true? Is it necessary? Is it constructive? Anything less is + unacceptable. +6. **Reactions require grace.** Angry responses are valid, but abusive language + and vindictive actions are toxic. When something happens that offends you, + handle it assertively, but be respectful. Escalate reasonably, and try to + allow the offender an opportunity to explain themselves, and possibly correct + the issue. +7. **Opinions are just that: opinions.** Each and every one of us, due to our + background and upbringing, have varying opinions. The fact of the matter, is + that is perfectly acceptable. Remember this: if you respect your own + opinions, you should respect the opinions of others. +8. **To err is human.** You might not intend it, but mistakes do happen and + contribute to build experience. Tolerate honest mistakes, and don't hesitate + to apologize if you make one yourself. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..09674d9 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,189 @@ +# CONTRIBUTING + +## RESOURCES + +If you wish to contribute to this project, please be sure to +read/subscribe to the following resources: + + - [Coding Standards](https://github.com/zendframework/zend-coding-standard) + - [Forums](https://discourse.zendframework.com/c/contributors) + - [Chat](https://zendframework-slack.herokuapp.com) + - [Code of Conduct](CODE_OF_CONDUCT.md) + +If you are working on new features or refactoring +[create a proposal](https://github.com/zendframework/ZendDeveloperTools/issues/new). + +## RUNNING TESTS + +To run tests: + +- Clone the repository: + + ```console + $ git clone git://github.com/zendframework/ZendDeveloperTools.git + $ cd ZendDeveloperTools + ``` + +- Install dependencies via composer: + + ```console + $ composer install + ``` + + If you don't have `composer` installed, please download it from https://getcomposer.org/download/ + +- Run the tests using the "test" command shipped in the `composer.json`: + + ```console + $ composer test + ``` + +You can turn on conditional tests with the `phpunit.xml` file. +To do so: + + - Copy `phpunit.xml.dist` file to `phpunit.xml` + - Edit `phpunit.xml` to enable any specific functionality you + want to test, as well as to provide test values to utilize. + +## Running Coding Standards Checks + +First, ensure you've installed dependencies via composer, per the previous +section on running tests. + +To run CS checks only: + +```console +$ composer cs-check +``` + +To attempt to automatically fix common CS issues: + +```console +$ composer cs-fix +``` + +If the above fixes any CS issues, please re-run the tests to ensure +they pass, and make sure you add and commit the changes after verification. + +## Recommended Workflow for Contributions + +Your first step is to establish a public repository from which we can +pull your work into the master repository. We recommend using +[GitHub](https://github.com), as that is where the component is already hosted. + +1. Setup a [GitHub account](https://github.com/), if you haven't yet +2. Fork the repository (https://github.com/zendframework/ZendDeveloperTools) +3. Clone the canonical repository locally and enter it. + + ```console + $ git clone git://github.com/zendframework/ZendDeveloperTools.git + $ cd ZendDeveloperTools + ``` + +4. Add a remote to your fork; substitute your GitHub username in the command + below. + + ```console + $ git remote add {username} git@github.com:{username}/ZendDeveloperTools.git + $ git fetch {username} + ``` + +### Keeping Up-to-Date + +Periodically, you should update your fork or personal repository to +match the canonical ZF repository. Assuming you have setup your local repository +per the instructions above, you can do the following: + + +```console +$ git checkout master +$ git fetch origin +$ git rebase origin/master +# OPTIONALLY, to keep your remote up-to-date - +$ git push {username} master:master +``` + +If you're tracking other branches -- for example, the "develop" branch, where +new feature development occurs -- you'll want to do the same operations for that +branch; simply substitute "develop" for "master". + +### Working on a patch + +We recommend you do each new feature or bugfix in a new branch. This simplifies +the task of code review as well as the task of merging your changes into the +canonical repository. + +A typical workflow will then consist of the following: + +1. Create a new local branch based off either your master or develop branch. +2. Switch to your new local branch. (This step can be combined with the + previous step with the use of `git checkout -b`.) +3. Do some work, commit, repeat as necessary. +4. Push the local branch to your remote repository. +5. Send a pull request. + +The mechanics of this process are actually quite trivial. Below, we will +create a branch for fixing an issue in the tracker. + +```console +$ git checkout -b hotfix/9295 +Switched to a new branch 'hotfix/9295' +``` + +... do some work ... + + +```console +$ git commit +``` + +... write your log message ... + + +```console +$ git push {username} hotfix/9295:hotfix/9295 +Counting objects: 38, done. +Delta compression using up to 2 threads. +Compression objects: 100% (18/18), done. +Writing objects: 100% (20/20), 8.19KiB, done. +Total 20 (delta 12), reused 0 (delta 0) +To ssh://git@github.com/{username}/ZendDeveloperTools.git + b5583aa..4f51698 HEAD -> master +``` + +To send a pull request, you have two options. + +If using GitHub, you can do the pull request from there. Navigate to +your repository, select the branch you just created, and then select the +"Pull Request" button in the upper right. Select the user/organization +"zendframework" (or whatever the upstream organization is) as the recipient. + +#### What branch to issue the pull request against? + +Which branch should you issue a pull request against? + +- For fixes against the stable release, issue the pull request against the + "master" branch. +- For new features, or fixes that introduce new elements to the public API (such + as new public methods or properties), issue the pull request against the + "develop" branch. + +### Branch Cleanup + +As you might imagine, if you are a frequent contributor, you'll start to +get a ton of branches both locally and on your remote. + +Once you know that your changes have been accepted to the master +repository, we suggest doing some cleanup of these branches. + +- Local branch cleanup + + ```console + $ git branch -d + ``` + +- Remote branch removal + + ```console + $ git push {username} : + ``` diff --git a/docs/ISSUE_TEMPLATE.md b/docs/ISSUE_TEMPLATE.md new file mode 100644 index 0000000..95f81c3 --- /dev/null +++ b/docs/ISSUE_TEMPLATE.md @@ -0,0 +1,19 @@ + - [ ] I was not able to find an [open](https://github.com/zendframework/ZendDeveloperTools/issues?q=is%3Aopen) or [closed](https://github.com/zendframework/ZendDeveloperTools/issues?q=is%3Aclosed) issue matching what I'm seeing. + - [ ] This is not a question. (Questions should be asked on [chat](https://zendframework.slack.com/) ([Signup here](https://zendframework-slack.herokuapp.com/)) or our [forums](https://discourse.zendframework.com/).) + +Provide a narrative description of what you are trying to accomplish. + +### Code to reproduce the issue + + + +```php +``` + +### Expected results + + + +### Actual results + + diff --git a/docs/PULL_REQUEST_TEMPLATE.md b/docs/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..f00d90c --- /dev/null +++ b/docs/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,25 @@ +Provide a narrative description of what you are trying to accomplish: + +- [ ] Are you fixing a bug? + - [ ] Detail how the bug is invoked currently. + - [ ] Detail the original, incorrect behavior. + - [ ] Detail the new, expected behavior. + - [ ] Base your feature on the `master` branch, and submit against that branch. + - [ ] Add a regression test that demonstrates the bug, and proves the fix. + - [ ] Add a `CHANGELOG.md` entry for the fix. + +- [ ] Are you creating a new feature? + - [ ] Why is the new feature needed? What purpose does it serve? + - [ ] How will users use the new feature? + - [ ] Base your feature on the `develop` branch, and submit against that branch. + - [ ] Add only one feature per pull request; split multiple features over multiple pull requests + - [ ] Add tests for the new feature. + - [ ] Add documentation for the new feature. + - [ ] Add a `CHANGELOG.md` entry for the new feature. + +- [ ] Is this related to quality assurance? + + +- [ ] Is this related to documentation? + + diff --git a/docs/SUPPORT.md b/docs/SUPPORT.md new file mode 100644 index 0000000..ee0eaf9 --- /dev/null +++ b/docs/SUPPORT.md @@ -0,0 +1,25 @@ +# Getting Support + +Zend Framework offers three support channels: + +- For real-time questions, use our + [chat](https://zendframework-slack.herokuapp.com) +- For detailed questions (e.g., those requiring examples) use our + [forums](https://discourse.zendframework.com/c/questions/components) +- To report issues, use this repository's + [issue tracker](https://github.com/zendframework/ZendDeveloperTools/issues/new) + +**DO NOT** use the issue tracker to ask questions; use chat or the forums for +that. Questions posed to the issue tracker will be closed. + +When reporting an issue, please include the following details: + +- A narrative description of what you are trying to accomplish. +- The minimum code necessary to reproduce the issue. +- The expected results of exercising that code. +- The actual results received. + +We may ask for additional details: what version of the library you are using, +and what PHP version was used to reproduce the issue. + +You may also submit a failing test case as a pull request.