From d6b0977afe8922bb720cdcee5d3b91f97a1e537e Mon Sep 17 00:00:00 2001 From: Brandon Frohs Date: Mon, 1 Jul 2019 13:09:36 -0400 Subject: [PATCH 1/5] Add issue templates for bug reports, feature requests, and usage questions --- .github/ISSUE_TEMPLATE/bug_report.md | 38 +++++++++++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 22 +++++++++++++ .github/ISSUE_TEMPLATE/how-to-use.md | 14 +++++++++ 3 files changed, 74 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/ISSUE_TEMPLATE/how-to-use.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..fcb3a65d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,38 @@ +--- +name: Bug report +about: Create a report to help improve PHPWord +labels: Bug Report + +--- + +### Describe the Bug + +A clear and concise description of what the bug is. + +### Steps to Reproduce + +Please provide a code sample that reproduces the issue. + +```php +addSection(); +$section->... +``` + +### Expected Behavior + +A clear and concise description of what you expected to happen. + +### Current Behavior + +What is the current behavior? + +### Context + +Please fill in your environment information: + +- PHP Version: +- PHPWord Version: diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..171e8378 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,22 @@ +--- +name: Feature request +about: Suggest an idea for this project +labels: Change Request + +--- + +### Is your feature request related to a problem? Please describe. + +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +### Describe the solution you'd like + +A clear and concise description of what you want to happen. + +### Describe alternatives you've considered + +A clear and concise description of any alternative solutions or features you've considered. + +### Additional context + +Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/how-to-use.md b/.github/ISSUE_TEMPLATE/how-to-use.md new file mode 100644 index 00000000..0fef996b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/how-to-use.md @@ -0,0 +1,14 @@ +--- +name: How to Use PHPWord +about: Find out how to use PHPWord +labels: WontFix + +--- + +***Please do not use the issue tracker to ask how to use PHPWord.*** + +Documentation is available on [Read the Docs](https://phpword.readthedocs.io/en/latest/). + +Sample code is in the [`/samples/` directory](https://github.com/PHPOffice/PHPWord/tree/develop/samples). + +Usage questions belong on [Stack Overflow](https://stackoverflow.com/questions/tagged/phpword). From e401adeb7e2f8e6efbbd6bd5b50807ee6863d5b8 Mon Sep 17 00:00:00 2001 From: Brandon Frohs Date: Mon, 1 Jul 2019 13:10:55 -0400 Subject: [PATCH 2/5] Update CONTRIBUTING to match reality and account for new issue templates --- CONTRIBUTING.md | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43ee0636..dbef13a6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,30 @@ # Contributing to PHPWord -PHPWord is built by the crowd and for the crowd. Every contribution is welcome; either by [submitting](https://github.com/PHPOffice/PHPWord/issues) bug issues or suggesting improvements, or in a more active form like [requesting](https://github.com/PHPOffice/PHPWord/pulls) a pull. +PHPWord is built by the crowd and for the crowd. Every contribution is welcome; either by [reporting a bug](https://github.com/PHPOffice/PHPWord/issues/new?labels=Bug+Report&template=bug_report.md) or [suggesting improvements](https://github.com/PHPOffice/PHPWord/issues/new?labels=Change+Request&template=feature_request.md), or in a more active form like [requesting a pull](https://github.com/PHPOffice/PHPWord/pulls). -We want to create a high quality document writer and reader library that people can use with more confidence and less bugs. We want to collaborate happily, code joyfully, and get alive merrily. Thus, below are some guidelines, that we expect to be followed by each contributor. +We want to create a high quality document writer and reader library that people can use with more confidence and fewer bugs. We want to collaborate happily, code joyfully, and live merrily. Thus, below are some guidelines that we expect to be followed by each contributor: -- **Be brief, but be bold**. State your issues briefly. But speak out your ideas loudly, even if you can't or don't know how to implement it right away. The world will be better with limitless innovations. -- **Follow PHP-FIG standards**. We follow PHP Standards Recommendations (PSRs) by [PHP Framework Interoperability Group](http://www.php-fig.org/). If you're not familiar with these standards, please, [familiarize yourself now](https://github.com/php-fig/fig-standards). Also, please, use [PHPCodeSniffer](http://pear.php.net/package/PHP_CodeSniffer/) to validate your code against PSRs. -- **Test your code**. Nobody else knows your code better than you. So, it's completely your mission to test the changes you made before pull request submission. We use [PHPUnit](https://phpunit.de/) for our testing purposes and recommend you using this tool too. [Here](https://phpunit.readthedocs.io) you can find documentation on how to write tests with PHPUnit, which helps us making PHPWord better day to day. Do not hesitate to smoke it carefully. It's a great investment in quality of your work, and it saves you years of life. -- **Request pull in separate branch**. Do not submit your request to the master branch. But create a separate branch named specifically for the issue that you addressed. Read [GitHub manual](https://help.github.com/articles/using-pull-requests) to find out more about this. If you are new to GitHub, read [this short manual](https://help.github.com/articles/fork-a-repo) to get yourself familiar with forks and how git works in general. [This video](http://www.youtube.com/watch?v=-zvHQXnBO6c) explains how to synchronize your Github Fork with the Branch of PHPWord. +- **Be brief, but be bold**. State your issues briefly. But speak out your ideas loudly, even if you can't or don't know how to implement them right away. The world will be better with limitless innovations. +- **Follow PHP-FIG standards**. We follow PHP Standards Recommendations (PSRs) by [PHP Framework Interoperability Group](http://www.php-fig.org/). If you're not familiar with these standards, [familiarize yourself now](https://github.com/php-fig/fig-standards). Also, please run `composer fix` to automatically fix your code to match these recommendations. +- **Test your code**. No one knows your code better than you, so we depend on you to test the changes you make before pull request submission. We use [PHPUnit](https://phpunit.de/) for our testing purposes and request that you use this tool too. Tests can be ran with `composer test`. [Documentation for writing tests with PHPUnit is available on Read the Docs.](https://phpunit.readthedocs.io) +- **Use best practices when submitting pull requests**. Create a separate branch named specifically for the issue that you are addressing. Read the [GitHub manual](https://help.github.com/articles/about-pull-requests) to learn more about pull requests and GitHub. If you are new to GitHub, read [this short manual](https://help.github.com/articles/fork-a-repo) to get yourself familiar with forks and how git works in general. [This video](http://www.youtube.com/watch?v=-zvHQXnBO6c) explains how to synchronize your fork on GitHub with the upstream branch from PHPWord. + +## Getting Started + +1. [Clone](https://help.github.com/en/articles/cloning-a-repository) [PHPWord](https://github.com/PHPOffice/PHPWord/) +2. [Install Composer](https://getcomposer.org/download/) if you don't already have it +3. Open your terminal and: + 1. Switch to the directory PHPWord was cloned to (e.g., `cd ~/Projects/PHPWord/`) + 2. Run `composer install` to install the dependencies + +You're ready to start working on PHPWord! Tests belong in the `/tests/PhpWord/` directory, the source code is in `/src/PhpWord/`, and any documentation should go in `/docs/`. Familiarize yourself with the codebase and try your hand at fixing [one of our outstanding issues](https://github.com/PHPOffice/PHPWord/issues). Before you get started, check the [existing pull requests](https://github.com/PHPOffice/PHPWord/pulls) to make sure no one else is already working on it. + +Once you have an issue you want to start working on, you'll need to write tests for it, and then you can start implementing the changes necessary to pass the new tests. To run the tests, you can run one of the following commands in your terminal: + +- `composer test-no-coverage` to run all of the tests +- `composer test` to run all of the tests and generate test coverage reports + +When you're ready to submit your new (and fully tested) feature, [submit a pull request to PHPWord](https://github.com/PHPOffice/PHPWord/issues/new). That's it. Thank you for your interest in PHPWord, and welcome! From 74e52ce71be3ab1fa1703c28cb2989a4df44dbbb Mon Sep 17 00:00:00 2001 From: Brandon Frohs Date: Mon, 1 Jul 2019 13:33:48 -0400 Subject: [PATCH 3/5] Remove the existing issue template --- docs/ISSUE_TEMPLATE.md | 35 ----------------------------------- 1 file changed, 35 deletions(-) delete mode 100644 docs/ISSUE_TEMPLATE.md diff --git a/docs/ISSUE_TEMPLATE.md b/docs/ISSUE_TEMPLATE.md deleted file mode 100644 index c7ed27d7..00000000 --- a/docs/ISSUE_TEMPLATE.md +++ /dev/null @@ -1,35 +0,0 @@ -This is: - -- [ ] a bug report -- [ ] a feature request -- [ ] **not** a usage question (ask them on https://stackoverflow.com/questions/tagged/phpword) - -### Expected Behavior - -Please describe the behavior you are expecting. - -### Current Behavior - -What is the current behavior? - -### Failure Information - -Please help provide information about the failure. - -### How to Reproduce - -Please provide a code sample that reproduces the issue. - -```php -addSection(); -$section->... -``` - -### Context - -* PHP version: -* PHPWord version: 0.14 From 71ac081cfa3cfc38bb8007dd195bba5fda12e80f Mon Sep 17 00:00:00 2001 From: Brandon Frohs Date: Mon, 1 Jul 2019 13:34:05 -0400 Subject: [PATCH 4/5] Add note about using `composer check` before submitting pull requests --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dbef13a6..ac262a0f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,7 +24,7 @@ Once you have an issue you want to start working on, you'll need to write tests - `composer test-no-coverage` to run all of the tests - `composer test` to run all of the tests and generate test coverage reports -When you're ready to submit your new (and fully tested) feature, [submit a pull request to PHPWord](https://github.com/PHPOffice/PHPWord/issues/new). +When you're ready to submit your new (and fully tested) feature, ensure `composer check` passes and [submit a pull request to PHPWord](https://github.com/PHPOffice/PHPWord/issues/new). That's it. Thank you for your interest in PHPWord, and welcome! From b13aa70ae9d451b8e6e6b049cbc11367fd90c0b6 Mon Sep 17 00:00:00 2001 From: Brandon Frohs Date: Mon, 1 Jul 2019 13:36:41 -0400 Subject: [PATCH 5/5] Move pull request template to avoid confusion --- {docs => .github}/PULL_REQUEST_TEMPLATE.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename {docs => .github}/PULL_REQUEST_TEMPLATE.md (100%) diff --git a/docs/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md similarity index 100% rename from docs/PULL_REQUEST_TEMPLATE.md rename to .github/PULL_REQUEST_TEMPLATE.md