Add contribution guidelines

.github/CONTRIBUTING.md

@@ -0,0 +1,103 @@
+# Contributions
+
+ClassicPress is a volunteer-driven open source project that thrives when we have multiple contributors working towards a common goal.
+
+Before contributing to this repository, please read our [Democracy page](https://www.classicpress.net/democracy/) to understand how we make decisions about what is included in ClassicPress, and our [roadmap](https://www.classicpress.net/roadmap/) to see what's already planned for the next couple of releases.
+
+The **petitions process** mentioned in our Democracy document is very important to help us prioritize new features based on the needs of our users. There are some [exceptions](https://www.classicpress.net/democracy/#democracy-exceptions) to this process for minor changes and bugfixes, but generally speaking it is a good idea to search or ask in one of our communication channels (see below) before undertaking a change, because most changes should go through the petitions process.
+
+Also, please be sure to follow our [code of conduct](https://www.classicpress.net/democracy/#democracy-conduct) in all interactions with ClassicPress community members.
+
+## Communication channels
+
+We encourage you to join and ask any questions you have about contributing.
+
+- [Slack](https://www.classicpress.net/join-slack/) - great for real-time chat, posting screenshots and asking questions about anything you're stuck on. Or just socializing.
+- [Petitions website](https://petitions.classicpress.net/) - for proposing new features or major changes for consideration by the community.
+- [GitHub issues](https://github.com/ClassicPress/ClassicPress/issues) - for proposing or discussing bugfixes, or minor improvements. Generally it is a good idea to create a petition for anything that may take a significant amount of time or that may have backwards compatibility implications.
+- [Forums](https://forums.classicpress.net/) - if you're not sure where to post your questions, searching and then posting on the forums is a good start. The forums are our most active community channel other than Slack.
+
+## Review criteria
+
+When evaluating bug fixes and other code changes in pull requests (PRs), we look for these things, ideally all of them:
+
+  1. The change impacts existing ClassicPress users. Otherwise, there are literally thousands of things we could look at, but we need to prioritize our development time. Right now the best tool we have for this is the [petitions site](https://petitions.classicpress.net/).
+  2. The change is not going to break backward compatibility, and has minimal effects on the existing plugin and theme ecosystem. A good way to evaluate the effects of a change on plugins or themes is to do a search on https://wpdirectory.net. (Major changes are also a possibility but require a planning effort around when and how they will be released, as well as agreement from the community per our [democratic process](https://www.classicpress.net/democracy/).)
+  3. The change has automated tests.
+  4. We understand the code change very well or can ask questions of someone who understands it very well.
+
+If your change meets all of these criteria then we will most likely accept it.
+
+We take a lot of care with our platform, and ClassicPress is maintained by volunteers in our free time. This means there may be some delays in merging pull requests.
+
+## What to work on?
+
+If you're not sure where to start contributing, here are some ideas:
+
+  - Review and test [existing PRs](https://github.com/ClassicPress/ClassicPress/pulls), especially looking at how well they fit the criteria described above. Let us know how you tested the changes and what you found. We need to be thorough and careful with any changes we make, and the more eyes we can get on our PRs the better.
+  - Bugfixes, you can find a list of known bugs on our [issues page](https://github.com/ClassicPress/ClassicPress/issues).
+  - Issues with the [`help wanted`](https://github.com/ClassicPress/ClassicPress/labels/help%20wanted) or [`good first issue`](https://github.com/ClassicPress/ClassicPress/labels/good%20first%20issue) labels.
+  - [Planned](https://petitions.classicpress.net/?view=planned) or [most wanted](https://petitions.classicpress.net/?view=most-wanted) feature requests from our petitions site.
+  - Exploratory PRs with your own suggested changes, but please remember these will be subject to review to make sure they are in line with the project's direction.
+
+## More information
+
+Here is some more information about a few subjects where we've noticed some frequent questions from contributors.
+
+### Automated tests
+
+Any change that introduces new code or changes behavior should have automated tests. These tests mostly use [PHPUnit](https://phpunit.de/) to verify the behavior of the many thousands of lines of PHP code in ClassicPress.
+
+If you're not familiar with automated tests, the concept is basically **code that runs other code** and verifies its behavior. There are lots of [existing examples](https://github.com/ClassicPress/ClassicPress/tree/develop/tests/phpunit/tests) already in the codebase.
+
+A good place to start with automated tests is to **run the existing test suite**. Here are brief steps to make this work:
+
+0. **Linux and OS X are supported.** Windows users will probably have an easier time using a Linux virtual machine or the "Windows Subsystem for Linux" shell available for recent versions of Windows.
+
+1. **Be sure your PHP installation supports the `mbstring` module.** If you're not sure, run `php -m` and look for `mbstring` in the list. If it's not present, and you're on Ubuntu or Debian Linux, you can run `sudo apt-get install php-mbstring` to fix this.
+
+2. **Install `phpunit` version `6.x`.** Example terminal commands:
+
+```
+wget https://phar.phpunit.de/phpunit-6.5.9.phar
+chmod +x phpunit-6.5.9.phar
+sudo mv phpunit-6.5.9.phar /usr/local/bin/phpunit
+phpunit --version
+```
+
+3. **Clone the ClassicPress `git` repository to your computer:**
+
+```
+git clone https://github.com/ClassicPress/ClassicPress.git
+cd ClassicPress
+```
+
+4. **Install MySQL and create an empty MySQL database.** The test suite will **delete all data** from all tables for whichever MySQL database is configured. *Use a separate database from any ClassicPress or WordPress installations on your computer*.
+
+5. **Set up a config file for the tests.** Copy `wp-tests-config-sample.php` to `wp-tests-config.php`, and enter your database credentials from the step above. *Use a separate database from any ClassicPress or WordPress installations on your computer*, because data in this database **will be deleted** with each test run.
+
+6. **Run the tests:**
+
+```
+phpunit
+```
+
+7. **Explore the existing tests** in the `tests/phpunit/tests` directory, look at how they work, edit them and break them, and write your own.
+
+_Note: this document is adapted from https://make.wordpress.org/core/handbook/testing/automated-testing/phpunit/ which contains more detail, but there are some differences in how automated tests work with recent versions of WordPress._
+
+### Backporting changes from WordPress
+
+ClassicPress version `1.0.0` is a fork of WordPress `4.9.x`, and since then, a number of changes have been made to WordPress for performance, bugfixes or new features.
+
+ClassicPress is mainly committed to keeping compatibility with the WordPress 4.9 branch. However, we're also open to merging bugfixes and enhancements from later versions of WordPress, **as long as they meet the criteria listed above**.
+
+There are some changes that we already know we want to backport because they fit into our plans for future versions of ClassicPress. You can find some examples under the [`WP backport` label](https://github.com/ClassicPress/ClassicPress/labels/WP%20backport).
+
+Otherwise, if you're interested in backporting a change from WordPress, then please explain in a pull request or issue what the change is, how it works, and why it's something that makes sense for ClassicPress to adopt. Often there is a lot of good discussion about each change in the relevant WordPress Trac tickets, and it makes the maintainers' job much easier to see this discussion summarized and linked.
+
+If you're not sure about any of that, then it's a good idea to ask first. A good way is to create an issue for the specific change you're interested in, along with links to the relevant WordPress changesets and tickets, and any other information you have about how the change works.
+
+Finally, when you're ready to backport a code change, identify the WordPress **changeset number** that you'd like to port, and run the `bin/backport-wp-commit.sh` script to apply the change to the code. If you're porting multiple changesets, you can use the `-c` option to this script to apply all the changesets to the same branch. With each commit there may be some merge conflicts to resolve.
+
+Using this script for all backports saves time for you and for the maintainers, and it also helps us track which WordPress changes we've already included. You can see a list of those changes [here](https://bots.classicpress.net/).

.github/ISSUE_TEMPLATE.md

@@ -4,11 +4,9 @@ Provide a general summary of the issue in the Title above.
 We welcome issues and pull requests for bugs and minor improvements, but please
 note that major changes must be approved and planned.
 
-To suggest new features or major changes, please visit our Petitions website at:
-https://petitions.classicpress.net/
+Please read our contributing guidelines for more information:
 
-For more details about our governance and change planning process, see:
-https://www.classicpress.net/democracy/
+https://github.com/ClassicPress/ClassicPress/blob/develop/.github/CONTRIBUTING.md
 -->
 
 ## Expected behavior
@@ -45,6 +43,6 @@ this bug. Include code to reproduce, if relevant.
 <!--
 How has this issue affected you? What are you trying to accomplish?
 
-Providing context helps us come up with a solution that is most useful in the
-real world.
+Providing context helps us come up with a solution that is most useful to our
+real-world users.
 -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,11 +4,9 @@ Provide a general summary of your changes in the Title above.
 We welcome pull requests for bug fixes and minor improvements, but please note
 that major changes must be approved and planned.
 
-To suggest new features or major changes, please visit our Petitions website at:
-https://petitions.classicpress.net/
+Please read our contributing guidelines for more information:
 
-For more details about our governance and change planning process, see:
-https://www.classicpress.net/democracy/
+https://github.com/ClassicPress/ClassicPress/blob/develop/.github/CONTRIBUTING.md
 -->
 
 ## Description
@@ -30,25 +28,29 @@ Please describe in detail how you tested your changes.
 Include details of your testing environment, and the tests you ran to see how
 your change affects other areas of the code, etc.
 
-Please include unit tests with new or changed code, if applicable.
+Please include automated tests with new or changed code, if applicable.
 -->
 
-## Screenshots (if appropriate):
+## Screenshots
+<!--
+Screenshots are very helpful for reviewers to quickly see how your change works.
+-->
 
-## Types of changes
+### Before
+<!--
+Insert screenshot(s) of the current behavior (before your changes) here.
+-->
+
+### After
 <!--
-What types of changes does your code introduce? Put an `x` in all the boxes
-that apply:
+Insert screenshot(s) of the new, proposed behavior (after your changes) here.
 -->
-- [ ] Bug fix (non-breaking change which fixes an issue)
-- [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to change)
 
-## Checklist:
+## Types of changes
 <!--
-Go over all the following points, and put an `x` in all the boxes that apply.
-If you're unsure about any of these, don't hesitate to ask. We're here to help!
+What types of changes does your code introduce?  Most PRs are one of the following:
+
+- Bug fix
+- New feature
+- Breaking change
 -->
-- [ ] My code follows the code style of this project.
-- [ ] My change requires a change to the documentation.
-- [ ] I have updated the documentation accordingly.

README.md

@@ -6,26 +6,19 @@
 
 ClassicPress is a hard fork of WordPress that serves the CMS-based business website market. We empower the people who create and support these websites, including plugin and theme developers.
 
-We welcome contributions of all kinds!  Have a look at
-[this repository's open issues](https://github.com/ClassicPress/ClassicPress/issues)
-and
-[our v1 project board](https://github.com/orgs/ClassicPress/projects/1),
-or if you're not sure where to start,
-[join us in Slack](https://join.slack.com/t/classicpress/shared_invite/enQtNDIwNjY2OTg1MjAxLWJiM2U2NmY3ZjFlZjQ4Zjk2OGI4ZTg3NzY1ZTU3NzI3OTRjMTU0YzAzOWUyZmZlODgyOWE1YTViYjcwY2Y5YzI)!
-
 For more information, see:
 
 - [The official ClassicPress website](https://www.classicpress.net/)
-- [The ClassicPress Democracy](https://www.classicpress.net/democracy/)
+- [The ClassicPress Democracy](https://www.classicpress.net/democracy/) (our governance structure)
 - [Suggest features](https://petitions.classicpress.net/)
 
-## Contributors
+## Contributions
 
 This project exists thanks to all the people who contribute and who have contributed in the past, whether as part of the long history of thousands of contributions to WordPress from many different people, or as contributions to ClassicPress itself.
 
-You can see a list of WordPress contributors by going to the [WordPress releases page](https://wordpress.org/news/category/releases/) and looking at the credits for each release.  All changes in WordPress 4.9.8 and earlier are part of ClassicPress, along with selected changes from later releases.
+Would you like to help? [Here is how you can start](https://github.com/ClassicPress/ClassicPress/blob/develop/.github/CONTRIBUTING.md).
 
-We are working on several ways to recognize people for their contributions to ClassicPress.  In the meantime, you can view a list of code contributions [here on GitHub](https://github.com/ClassicPress/ClassicPress/compare/LAST_WP_COMMIT...develop).
+We are working on several ways to recognize people for their contributions to ClassicPress. In the meantime, you can view a list of code contributions [here on GitHub](https://github.com/ClassicPress/ClassicPress/compare/LAST_WP_COMMIT...develop).
 
 ## Donate to support ClassicPress