diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..8a317b5eb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,66 @@ +# Instructions For Logging Issues + +## 1. Search For Duplicates + +[Search the existing issues](/search?type=Issues) before logging a new one. + +Some search tips: +* *Don't* restrict your search to only open issues. An issue with a title similar to yours may have been closed as a duplicate of one with a less-findable title. +* Search for the title of the issue you're about to log. This sounds obvious but 80% of the time this is sufficient to find a duplicate when one exists. +* Read more than the first page of results. Many bugs here use the same words so relevancy sorting is not particularly strong. +* If you have a crash, search for the first few topmost function names shown in the call stack. + +## 2. Did You Find A Bug? + +When logging a bug, please be sure to include the following: + +* What version of the package/plugin are you using +* If at all possible, an *isolated* way to reproduce the behavior +* The behavior you expect to see, and the actual behavior + +## 3. Do You Have A Suggestion? + +We also accept suggestions in the issue tracker. Be sure to [search](/search?q=is:issue) first. + + +In general, things we find useful when reviewing suggestions are: +* A description of the problem you're trying to solve +* An overview of the suggested solution +* Examples of how the suggestion would work in various places + * Code examples showing e.g. "this would be an error, this wouldn't" + * Code examples showing usage (if possible) +* If relevant, precedent in other frameworks or libraries can be useful for establishing context and expected behavior + +# Instructions For Contributing Code + +## What You'll Need + +0. [A bug or feature you want to work on](/labels/help%20wanted)! +1. [A GitHub account](https://github.com/join). +2. A working copy of the code. See [DEVELOPMENT](/docs/DEVELOPMENT.md) + +## Housekeeping + +Your pull request should: + +* Include a description of what your change intends to do +* Be based on reasonably recent commit in the **canary** branch +* Include adequate tests + * At least one test should fail in the absence of your non-test code changes. If your PR does not match this criteria, please specify why + * Tests should include reasonable permutations of the target fix/change + * Include baseline changes with your change +* Contain proper [semantic commit messages](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716#gistcomment-3711094) as follows: + + ``` + []: () + │ │ | │ + | | | └─> Summary in present tense. Not capitalized. No period at the end. + | | | + │ │ └─> Issue # (optional): Issue number if related to bug database. + │ │ + │ └─> Scope (optional): eg. common, compiler, authentication, core + │ + └─> Type: chore, docs, feat, fix, refactor, style, or test. + ``` + +* To avoid line ending issues, set `autocrlf = input` and `whitespace = cr-at-eol` in your git configuration diff --git a/README.md b/README.md index b8fd1974d..70a29ead6 100644 --- a/README.md +++ b/README.md @@ -43,17 +43,17 @@ To enable post previews, set your front-end app URL on the WordPress Settings ### Plugin Features -- **[Headless post previewing](/docs/previews/README.md)** - - OAuth token authentication creation - - Preview and draft link rewrites in WP Admin to redirect to the front-end -- **Smart content redirects** - - Automatically redirects content from the WP site to the front-end site to minimize site visitors’ confusion and avoid SEO penalties for duplicate content - - Redirects hyperlinks inserted into posts’ content to the front-end site -- **Disable WP theme admin pages** - - Prevents access to admin pages that have no effect on the headless front-end appearance, such as Appearance → Themes. -- **Ability to define custom menus in a GUI** -- **Additional data exposed through WPGraphQL** - - Block stylesheets +* **[Headless post previewing](/docs/previews/README.md)** + * OAuth token authentication creation + * Preview and draft link rewrites in WP Admin to redirect to the front-end +* **Smart content redirects** + * Automatically redirects content from the WP site to the front-end site to minimize site visitors’ confusion and avoid SEO penalties for duplicate content + * Redirects hyperlinks inserted into posts’ content to the front-end site +* **Disable WP theme admin pages** + * Prevents access to admin pages that have no effect on the headless front-end appearance, such as Appearance → Themes. +* **Ability to define custom menus in a GUI** +* **Additional data exposed through WPGraphQL** + * Block stylesheets ### npm Package Features @@ -95,14 +95,18 @@ npm install --save @wpengine/headless ## Guides -- [Getting started with the Headless Framework](/docs/getting-started/README.md) -- [Enabling post previews in Next.js](/docs/previews/README.md) -- [Using the WordPress template hieararchy in Next.js](/docs/previews/README.md) +* [Getting started with the Headless Framework](/docs/getting-started/README.md) +* [Enabling post previews in Next.js](/docs/previews/README.md) +* [Using the WordPress template hieararchy in Next.js](/docs/previews/README.md) -## Contributing +## Contribute -Since we're in the early stages of development, we are not currently accepting outside contributions; although, we are -interested in any problems that you encounter while using the framework. +There are many ways to [contribute](/CONTRIBUTING.md) to this project. + +* [Discuss open issues](/issues) to help define the future of the project. +* [Submit bugs](/issues) and help us verify fixes as they are checked in. +* Review and discuss the [source code changes](pulls). +* [Contribute bug fixes](/CONTRIBUTING.md) ### [Development Guide](/docs/DEVELOPMENT.md) @@ -111,5 +115,5 @@ streamline your development process. ### License -- npm packages in this repository are MIT licensed -- WordPress plugins in this repository are GPLv2+ licensed +* npm packages in this repository are MIT licensed +* WordPress plugins in this repository are GPLv2+ licensed diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index ced6bb0b9..b243d1c57 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -1,8 +1,11 @@ # Contributing -Since we're in the early stages of development, we are not currently accepting outside contributions; although, we are interested in any problems that you encounter while using the framework. +There are many ways to [contribute](/CONTRIBUTING.md) to this project. -Create an issue in this repository to report bugs or feature requests. +* [Discuss open issues](/issues) to help define the future of the project. +* [Submit bugs](/issues) and help us verify fixes as they are checked in. +* Review and discuss the [source code changes](pulls). +* [Contribute bug fixes](/CONTRIBUTING.md) ## Project Structure @@ -57,7 +60,7 @@ composer phpcs:fix **WordPress Unit Tests** To run WordPress unit tests, set up the test framework: - + ``` /bin/bash /path/to/headless-framework/plugins/wpe-headless/tests/install-wp-tests.sh wpe_headless_tests db_name db_password ```