Merge pull request #24242 from woocommerce/update-contributing-docs
Update WooCommerce developer documentation
This commit is contained in:
Rodrigo Primo
GitHub
commit
132d785c65
|
|
@ -1,16 +1,48 @@
|
|||
# Contributing to WooCommerce ✨
|
||||
|
||||
There are many ways to contribute to the WooCommerce project!
|
||||
WooCommerce powers many online stores across the internet, and your help making it even more awesome will be greatly appreciated :)
|
||||
|
||||
- Translating strings into your language.
|
||||
- Answering questions on GitHub and within the various WooCommerce communities.
|
||||
There are many ways to contribute to the project!
|
||||
|
||||
- [Translating strings into your language](https://github.com/woocommerce/woocommerce/wiki/Translating-WooCommerce).
|
||||
- Answering questions on the various WooCommerce communities like the [WP.org support forums](https://wordpress.org/support/plugin/woocommerce/).
|
||||
- Testing open [issues](https://github.com/woocommerce/woocommerce/issues) or [pull requests](https://github.com/woocommerce/woocommerce/pulls) and sharing your findings in a comment.
|
||||
- Testing WooCommerce beta versions and release candidates. Those are announced in the [WooCommerce development blog](https://woocommerce.wordpress.com/).
|
||||
- Submitting fixes, improvements, and enhancements.
|
||||
- To disclose a security issue to our team, [please submit a report via HackerOne](https://hackerone.com/automattic/).
|
||||
|
||||
WooCommerce currently powers 30% of all online stores across the internet, and your help making it even more awesome will be greatly appreciated :)
|
||||
If you wish to contribute code, please read the information in the sections below. Then [fork](https://help.github.com/articles/fork-a-repo/) WooCommerce, commit your changes, and [submit a pull request](https://help.github.com/articles/using-pull-requests/) 🎉
|
||||
|
||||
If you think something can be improved and you wish to contribute code,
|
||||
[fork](https://help.github.com/articles/fork-a-repo/) WooCommerce, commit your changes,
|
||||
and [send a pull request](https://help.github.com/articles/using-pull-requests/). We'll be happy to review your changes!
|
||||
We use the `help wanted` label to mark issues that are suitable for new contributors. You can find all the issues with this label [here](https://github.com/woocommerce/woocommerce/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22).
|
||||
|
||||
WooCommerce is licensed under the GPLv3+, and all contributions to the project will be released under the same license. You maintain copyright over any contribution you make, and by submitting a pull request, you are agreeing to release that contribution under the GPLv3+ license.
|
||||
|
||||
If you have questions about the process to contribute code or want to discuss details of your contribution, you can contact WooCommerce core developers on the #core channel in the [WooCommerce community Slack](https://woocommerce.com/community-slack/).
|
||||
|
||||
## Getting started
|
||||
|
||||
- [How to set up WooCommerce development environment](https://github.com/woocommerce/woocommerce/wiki/How-to-set-up-WooCommerce-development-environment)
|
||||
- [Git Flow](https://github.com/woocommerce/woocommerce/wiki/WooCommerce-Git-Flow)
|
||||
- [Minification of SCSS and JS](https://github.com/woocommerce/woocommerce/wiki/Minification-of-SCSS-and-JS)
|
||||
- [String localisation guidelines](https://github.com/woocommerce/woocommerce/wiki/String-localisation-guidelines)
|
||||
- [Running unit tests](https://github.com/woocommerce/woocommerce/blob/master/tests/README.md)
|
||||
- [Running e2e tests](https://github.com/woocommerce/woocommerce/wiki/End-to-end-Testing)
|
||||
|
||||
## Coding Guidelines and Development 🛠
|
||||
|
||||
- Ensure you stick to the [WordPress Coding Standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/)
|
||||
- Run our build process described in the document on [how to set up WooCommerce development environment](https://github.com/woocommerce/woocommerce/wiki/How-to-set-up-WooCommerce-development-environment), it will install our pre-commit hook, code sniffs, dependencies, and more.
|
||||
- Whenever possible please fix pre-existing code standards errors in the files that you change. It is ok to skip that for larger files or complex fixes.
|
||||
- Ensure you use LF line endings in your code editor. Use [EditorConfig](http://editorconfig.org/) if your editor supports it so that indentation, line endings and other settings are auto configured.
|
||||
- When committing, reference your issue number (#1234) and include a note about the fix.
|
||||
- Ensure that your code supports the minimum supported versions of PHP and WordPress; this is shown at the top of the `readme.txt` file.
|
||||
- Push the changes to your fork and submit a pull request on the master branch of the WooCommerce repository.
|
||||
- Make sure to write good and detailed commit messages (see [this post](https://chris.beams.io/posts/git-commit/) for more on this) and follow all the applicable sections of the pull request template.
|
||||
- Please avoid modifying the changelog directly or updating the .pot files. These will be updated by the WooCommerce team.
|
||||
|
||||
If you are contributing code to the REST API or editor blocks, these are developed in external packages.
|
||||
- [WooCommerce REST API package](https://github.com/woocommerce/woocommerce-rest-api)
|
||||
- [Blocks](https://github.com/woocommerce/woocommerce-gutenberg-products-block)
|
||||
|
||||
## Feature Requests 🚀
|
||||
|
||||
|
|
@ -19,94 +51,3 @@ Feature requests can be [submitted to our issue tracker](https://github.com/wooc
|
|||
Feature request issues will remain closed until we see sufficient interest via comments and [👍 reactions](https://help.github.com/articles/about-discussions-in-issues-and-pull-requests/) from the community.
|
||||
|
||||
You can see a [list of current feature requests which require votes here](https://github.com/woocommerce/woocommerce/issues?q=label%3A%22votes+needed%22+label%3Aenhancement+sort%3Areactions-%2B1-desc+is%3Aclosed).
|
||||
|
||||
## Technical Support / Questions ❓
|
||||
|
||||
We don't offer technical support on GitHub so we recommend using the following:
|
||||
|
||||
**Reading our documentation**
|
||||
Usage docs can be found here: https://docs.woocommerce.com/
|
||||
|
||||
If you have a problem, you may want to start with the self help guide here: https://docs.woocommerce.com/document/woocommerce-self-service-guide/
|
||||
|
||||
**Technical support for premium extensions or if you're a WooCommerce.com customer**
|
||||
from a human being - submit a ticket via the helpdesk
|
||||
https://woocommerce.com/contact-us/
|
||||
|
||||
**General usage and development questions**
|
||||
- WooCommerce Slack Community: https://woocommerce.com/community-slack/
|
||||
- WordPress.org Forums: https://wordpress.org/support/plugin/woocommerce
|
||||
- The WooCommerce Help and Share Facebook group
|
||||
|
||||
**Customizations**
|
||||
- [WooExperts](https://woocommerce.com/experts/)
|
||||
- [Codeable](https://codeable.io/)
|
||||
|
||||
## Build process 🛠
|
||||
|
||||
The source code found on GitHub does not contain compiled CSS or Javascript, and is missing some functionality such as Gutenberg Blocks and the REST API, until the build process is ran.
|
||||
|
||||
To run the build process, in a terminal go to your WooCommerce installation and run:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
composer install
|
||||
npm run build
|
||||
```
|
||||
|
||||
To get your development environment running we recommend [reading here](https://github.com/woocommerce/woocommerce/wiki/How-to-set-up-WooCommerce-development-environment).
|
||||
|
||||
## Coding Guidelines and Development 🛠
|
||||
|
||||
- **Ensure you stick to the [WordPress Coding Standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/)**
|
||||
- Run our build process described in the section above, it will install our pre-commit hook, code sniffs, dependencies, and more.
|
||||
- Ensure you use LF line endings in your code editor. Use [EditorConfig](http://editorconfig.org/) if your editor supports it so that indentation, line endings and other settings are auto configured.
|
||||
- When committing, reference your issue number (#1234) and include a note about the fix.
|
||||
- Ensure that your code supports the minimum supported versions of PHP and WordPress; this is shown at the top of the `readme.txt` file.
|
||||
- Push the changes to your fork and submit a pull request on the master branch of the WooCommerce repository.
|
||||
|
||||
Please avoid modifying the change-log directly or updating the .pot files. These will be updated by the WooCommerce team.
|
||||
|
||||
If you are contributing code to the REST API or editor blocks, these are developed in external packages.
|
||||
- [WooCommerce REST API package](https://github.com/woocommerce/woocommerce-rest-api)
|
||||
- [Blocks](https://github.com/woocommerce/woocommerce-gutenberg-products-block)
|
||||
|
||||
## Translating WooCommerce 💬
|
||||
|
||||
We have a [project on translate.wordpress.org](https://translate.wordpress.org/projects/wp-plugins/woocommerce). You can join the localization team of your language and help by translating WooCommerce. [Find more about using joining a language team and using GlotPress](https://make.wordpress.org/polyglots/handbook/tools/glotpress-translate-wordpress-org/).
|
||||
|
||||
If WooCommerce is already 100% translated for your language, join the team anyway! We regularly update our language files and there will definitely be need of your help soon.
|
||||
|
||||
### Glossary & Style Guide
|
||||
|
||||
Please refer to this page on the [Translator Handbook](https://make.wordpress.org/polyglots/handbook/translating/glossary-style-guide/) for information about the glossary and the style guide.
|
||||
|
||||
We maintain the WooCommerce glossary [on this shared Google Sheet](https://docs.google.com/spreadsheets/d/1Pobl2nNWieaSpZND9-Bwa4G8pnMU7QYceKsXuWCwSxQ/edit?usp=sharing). You can use it as a template for creating your own glossary.
|
||||
Please download the file by going to **File > Download as > Comma-separated values (.csv, current sheet)** and save it on your computer/Mac. Open it with your favourite CSV editor (or re-upload it on your own Google Drive) and edit it.
|
||||
|
||||
Make sure to edit the second column’s header by using your own language’s code (eg. for Italian you would use `it`, for Portuguese (Brazil) you would use `pt-BR`).
|
||||
|
||||
Write the translated entry in this column and translate the entry description as well.
|
||||
Don’t change other columns headers and value, but feel free to add new entries.
|
||||
|
||||
When your CSV is ready, import it on GlotPress.
|
||||
|
||||
_**Warning**: Importing a CSV does not replace existing items, they will be created again. We suggest to import them only when first creating the glossary._
|
||||
|
||||
Each translation editor will take care of updating the glossary on GlotPress by editing/adding items when needed.
|
||||
|
||||
_**Note**: Only editors can create/import and edit glossaries and glossary items on GlotPress. Anyone can suggest new items to add to the glossary or translate them._
|
||||
|
||||
**Style Guides Available**
|
||||
|
||||
We don’t have a Style Guide template available, so feel free to create your own. Here are the style guides available at the moment:
|
||||
|
||||
* [Italian](https://docs.google.com/document/d/1rspopHOiTL-5-PjyG5eJxjkYk6JkzqVbyS24OdA052o/edit?usp=sharing)
|
||||
|
||||
If you created a style guide for your language, please let us know so we can add it in the list above. You can also add it by yourself by submitting a PR for this file.
|
||||
|
||||
### Translating Video Tutorials
|
||||
|
||||
Another valuable way to help is by translating our growing library of WooCommerce video tutorials. Check out the [Translating Our Videos](https://docs.woocommerce.com/document/translating-our-videos/) doc and join in!
|
||||
|
||||
By translating video tutorials you'll be helping non-English speaking users and people affected by disabilities to get to grips with using WooCommerce for the first time, and to go on and create their businesses and make a living! That's something to be proud of and if you choose to dive into this area, we salute you.
|
||||
|
|
|
|||
|
|
@ -16,6 +16,7 @@ If you are not a developer, please use the [WooCommerce plugin page](https://wor
|
|||
|
||||
## Documentation
|
||||
* [WooCommerce Documentation](https://docs.woocommerce.com/documentation/plugins/woocommerce/)
|
||||
* [WooCommerce Developer Documentation](https://github.com/woocommerce/woocommerce/wiki)
|
||||
* [WooCommerce Code Reference](https://docs.woocommerce.com/wc-apidocs/)
|
||||
* [WooCommerce REST API Docs](https://woocommerce.github.io/woocommerce-rest-api-docs/)
|
||||
|
||||
|
|
@ -25,8 +26,11 @@ To disclose a security issue to our team, [please submit a report via HackerOne
|
|||
## Support
|
||||
This repository is not suitable for support. Please don't use our issue tracker for support requests, but for core WooCommerce issues only. Support can take place through the appropriate channels:
|
||||
|
||||
* The [WooCommerce premium support portal](https://woocommerce.com/my-account/create-a-ticket/) for customers who have purchased themes or extensions.
|
||||
* If you have a problem, you may want to start with the [self help guide](https://docs.woocommerce.com/document/woocommerce-self-service-guide/).
|
||||
* The [WooCommerce.com premium support portal](https://woocommerce.com/contact-us/ ) for customers who have purchased themes or extensions.
|
||||
* [Our community forum on wp.org](https://wordpress.org/support/plugin/woocommerce) which is available for all WooCommerce users.
|
||||
* The WooCommerce Help and Share Facebook group.
|
||||
* For customizations, you may want to check our list of [WooExperts](https://woocommerce.com/experts/) or [Codeable](https://codeable.io/).
|
||||
|
||||
Support requests in issues on this repository will be closed on sight.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,46 +2,43 @@
|
|||
|
||||
## Initial Setup
|
||||
|
||||
1) Install [PHPUnit](http://phpunit.de/) by following their [installation guide](https://phpunit.de/getting-started.html). If you've installed it correctly, this should display the version:
|
||||
From the WooCommerce root directory (if you are using VVV you might need to `vagrant ssh` first), run the following:
|
||||
|
||||
1. Install [PHPUnit](http://phpunit.de/) via Composer by running:
|
||||
```
|
||||
$ phpunit --version
|
||||
$ composer install
|
||||
```
|
||||
|
||||
2) Install WordPress and the WP Unit Test lib using the `install.sh` script. Change to the plugin root directory and type:
|
||||
|
||||
2. Install WordPress and the WP Unit Test lib using the `install.sh` script:
|
||||
```
|
||||
$ tests/bin/install.sh <db-name> <db-user> <db-password> [db-host]
|
||||
```
|
||||
|
||||
The `<db-password>` will be set as given. Previously, you would have needed to escape certain characters (forward & backward slashes, and ampersand), but install.sh now escapes them when it needs to internally. You may still need to quote strings with backslashes to prevent them from being processed by the shell or other programs.
|
||||
You may need to quote strings with backslashes to prevent them from being processed by the shell or other programs.
|
||||
|
||||
Sample usages:
|
||||
Example:
|
||||
|
||||
$ tests/bin/install.sh woocommerce_tests root root
|
||||
|
||||
# The actual password only has a single backslash, but it's escaped
|
||||
# to prevent the shell and PHP from treating it as a backspace character
|
||||
$ tests/bin/install.sh woocommerce_tests root 'a\\b/&'
|
||||
# Previously, the password would have had to be passed as 'a\\\\b\/\&'
|
||||
# woocommerce_tests is the database name and root is both the MySQL user and its password.
|
||||
|
||||
**Important**: The `<db-name>` database will be created if it doesn't exist and all data will be removed during testing.
|
||||
|
||||
## Running Tests
|
||||
|
||||
Simply change to the plugin root directory and type:
|
||||
Change to the plugin root directory and type:
|
||||
|
||||
$ phpunit
|
||||
$ vendor/bin/phpunit
|
||||
|
||||
The tests will execute and you'll be presented with a summary. Code coverage documentation is automatically generated as HTML in the `tmp/coverage` directory.
|
||||
The tests will execute and you'll be presented with a summary.
|
||||
|
||||
You can run specific tests by providing the path and filename to the test class:
|
||||
|
||||
$ phpunit tests/unit-tests/api/orders
|
||||
$ vendor/bin/phpunit tests/unit-tests/importer/product.php
|
||||
|
||||
A text code coverage summary can be displayed using the `--coverage-text` option:
|
||||
|
||||
$ phpunit --coverage-text
|
||||
$ vendor/bin/phpunit --coverage-text
|
||||
|
||||
## Writing Tests
|
||||
|
||||
|
|
@ -51,7 +48,7 @@ A text code coverage summary can be displayed using the `--coverage-text` option
|
|||
* Use the test coverage HTML report (under `tmp/coverage/index.html`) to examine which lines your tests are covering and aim for 100% coverage
|
||||
* For code that cannot be tested (e.g. they require a certain PHP version), you can exclude them from coverage using a comment: `// @codeCoverageIgnoreStart` and `// @codeCoverageIgnoreEnd`. For example, see [`wc_round_tax_total()`](https://github.com/woocommerce/woocommerce/blob/35f83867736713955fa2c4f463a024578bb88795/includes/wc-formatting-functions.php#L208-L219)
|
||||
* In addition to covering each line of a method/function, make sure to test common input and edge cases.
|
||||
* Prefer `assertSame()` where possible as it tests both type & equality
|
||||
* Prefer `assertSame()` where possible as it tests both type and value
|
||||
* Remember that only methods prefixed with `test` will be run so use helper methods liberally to keep test methods small and reduce code duplication. If there is a common helper method used in multiple test files, consider adding it to the `WC_Unit_Test_Case` class so it can be shared by all test cases
|
||||
* Filters persist between test cases so be sure to remove them in your test method or in the `tearDown()` method.
|
||||
* Use data providers where possible. Be sure that their name is like `data_provider_function_to_test` (i.e. the data provider for `test_is_postcode` would be `data_provider_test_is_postcode`). Read more about data providers [here](https://phpunit.de/manual/current/en/writing-tests-for-phpunit.html#writing-tests-for-phpunit.data-providers).
|
||||
|
|
@ -62,4 +59,4 @@ Tests are automatically run with [Travis-CI](https://travis-ci.org/woocommerce/w
|
|||
|
||||
## Code Coverage
|
||||
|
||||
Code coverage is available on [Scrutinizer](https://scrutinizer-ci.com/g/woocommerce/woocommerce/) and [Code Climate](https://codeclimate.com/github/woocommerce/woocommerce) which receives updated data after each Travis build.
|
||||
Code coverage is available on [Scrutinizer](https://scrutinizer-ci.com/g/woocommerce/woocommerce/) and [Codecov](https://codecov.io/gh/woocommerce/woocommerce/) which receives updated data after each Travis build.
|
||||
|
|
|
|||
Loading…
Reference in New Issue