| 1 |
# Shared tasks library docs |
| 2 |
|
| 3 |
## Project conventions |
| 4 |
|
| 5 |
1. Make sure your plugin main .php file is named like your project name (`name` property of your `package.json` file). |
| 6 |
2. If your project keeps plugin version number reference outside the file header PHP comment, please make sure it's in a define. E.g. like this: |
| 7 |
`define('SNAPSHOT_VERSION', '3.1.5');` |
| 8 |
If your project uses a variable to keep track of the current version, assign the value of this define to it. See snapshot project for an example of this. |
| 9 |
|
| 10 |
## Gruntfile conventions and practices |
| 11 |
1. Require the shared task loader at the top of your `Gruntfile.js`, passing `grunt` variable to the require, like this: |
| 12 |
`var wpmudev = require('./shared-tasks/loader')(grunt);` |
| 13 |
2. Automatic fileset types: |
| 14 |
- Externals: if your project uses external libraries outside submodules (i.e. stuff that should be included in a release, but not e.g. processed via linters), add those paths in yourself. See smartcrawl project for an example of this. Note: git submodules will be added to the list automatically. |
| 15 |
- Free (wordpress.org) project releases: WPMU DEV Dashboard will be automatically excluded from free project release packaging. To omit other paths, add them to the `free` files queue manually. |
| 16 |
- Full (DEV proper) project releases: `readme.txt` and any screenshot images in the root project folder will be excluded from full project release packaging. To omit other paths, add them to the `full` files queue manually. |
| 17 |
- Cleanup: the `dist` folder will be treated as an intermediate area and will be cleaned up before releasing, as well as any `.zip` files in the root directory. To include other paths in automated cleanup, add them to the `clean` queue manually. |
| 18 |
3. Shared tasks enforces a certain interface - namely, your `Gruntfile.js` has to expose a task named `release`. Running this task has to end up with newly created, self-sufficient, versioned distributable archive in the `builds` directory. |
| 19 |
4. Use the supplied `wpmudev_release` task in your `release` task body, and supply any release- and project- specific info in its configuration property. See smartcrawl and snapshot projects for an example of this. The `wpmudev_release` task will also automatically update your project's version numbers, check changelog, update translation catalogs and, if everything's up to spec, commit changes and tag the release. |
| 20 |
5. It is recommended to maintain a separate, simpler packaging task, to produce a simplified current work snapshot archive. See snapshot and smartcrawl projects for an example of this. |
| 21 |
6. You do not need to maintain a separate project `makepot` task - this comes with the library, and will be called automatically from `wpmudev_release` task. |
| 22 |
7. You can - but do not have to - maintain separate `phpcs` and `jshint` tasks, the library will try to use system linters if it can via the `wpmudev_lint` task. It will first try to use the default configuration, if it's present. |
| 23 |
|
| 24 |
## Work conventions and tools |
| 25 |
|
| 26 |
The project comes with grunt tasks to facilitate adhering to conventions when working on bugs and features. |
| 27 |
|
| 28 |
To make use of them, you will need an ID for your task (`TASKID`). If you are working on an Asana task, your task ID will be the last numeric portion of the Asana task URL. For an example, for this task: https://app.asana.com/0/46496453944769/467725328362050/f, the `TASKID` would be `467725328362050`. |
| 29 |
|
| 30 |
If you are *not* working on an Asana task, consider creating one :) Otherwise, use a quoted sentence that briefly, yet sufficiently explains what you're working on as your `TASKID`. |
| 31 |
|
| 32 |
### Examples |
| 33 |
|
| 34 |
Fixing a bug with Asana task assigned: |
| 35 |
`grunt bugfix:467725328362050` |
| 36 |
|
| 37 |
Adding a feature with Asana task assigned: |
| 38 |
`grunt featureadd:467725328362050` |
| 39 |
|
| 40 |
Fixing a bug with *no* Asana task assigned: |
| 41 |
`grunt bugfix:"SEO Analysis"` |
| 42 |
|
| 43 |
Adding a feature with *no* Asana task assigned: |
| 44 |
`grunt featureadd:"Flying saucers"` |
| 45 |
|
| 46 |
#### What this does |
| 47 |
|
| 48 |
Runing this task will: |
| 49 |
|
| 50 |
1. ... create an appropriately named branch (`fix/<TASKID>` for `bugfix` task, `new/<TASKID>` for `featureadd` task) |
| 51 |
2. ... add a temporary changelog entry at the top of your `changelog.txt` with task info. This serves multiple purposes: |
| 52 |
- It is easier for QA staff to run their tests with efficiency. |
| 53 |
- When it is release time, it will be easier to compile the proper changelog entry with this info there. |
| 54 |
3. ... make an initial commit in your new branch and leave to do your work. |
| 55 |
|
| 56 |
These auto-created branches will not be pushed to BitBucket unless you do so yourself. If your work is going to take longer than just an hour or two, consider pushing it. |
| 57 |
|
| 58 |
#### Implementing fixes and features atop of a previous release |
| 59 |
|
| 60 |
The newly auto-created branch will be based off of your current branch and commit. If you want to base it off of a different source (e.g. you want to fix a bug in a released version but the main work already progressed on), you can include an optional second parameter to tasks. For an example, to start working on a fix for bug report 467725328362050 in v2.0.1 release, use this command: `grunt bugfix:467725328362050:2.0.1` |
| 61 |
|
| 62 |
### Once I'm done... |
| 63 |
|
| 64 |
When you're done working and the fix or feature is to be incorporated into the different branch, either merge it, or push your branch and submit a pull request. |
| 65 |
|
