| 1 | # bbPress |
|---|
| 2 | |
|---|
| 3 | bbPress is forum software with a twist from the creators of WordPress. Easily setup discussion forums inside your WordPress.org powered site. |
|---|
| 4 | |
|---|
| 5 | Have you ever been frustrated with forum or bulletin board software that was slow, bloated and always got your server hacked? bbPress is focused on ease of integration, ease of use, web standards, and speed. |
|---|
| 6 | |
|---|
| 7 | We're keeping things as small and light as possible while still allowing for great add-on features through WordPress's extensive plugin system. What does all that mean? bbPress is lean, mean, and ready to take on any job you throw at it. |
|---|
| 8 | |
|---|
| 9 | ## The new development repo |
|---|
| 10 | |
|---|
| 11 | As part of bbPress 2.6 we have revamped our development workflow to streamline and automate many of the tasks that come up day-to-day. |
|---|
| 12 | |
|---|
| 13 | * Validate and test i18n support and generating *pot* files for easy translation into other languages |
|---|
| 14 | * Generate RTL CSS for our international locales that use *right-to-left* text such as Arabic and Hebrew |
|---|
| 15 | * Compile bbPress' admin themes SCSS into CSS |
|---|
| 16 | * Minimize CSS, RTL CSS and JavaScript files |
|---|
| 17 | * Validating our JavaScript files for errors and coding best practices |
|---|
| 18 | * PHPUnit testing framework for PHP integrated with Travis-CI |
|---|
| 19 | |
|---|
| 20 | ### The src directory |
|---|
| 21 | |
|---|
| 22 | The `/src` directory is the bbPress core source. All of the existing bbPress core files have been moved into this directory. You’ll develop and test against this directory as usual, but the real power will come from using the rest of the tools in the repository. The contents are optimized for development, not production (this means uncompressed CSS and JavaScript files and uncompiled SCSS files). |
|---|
| 23 | |
|---|
| 24 | ### The tests directory |
|---|
| 25 | |
|---|
| 26 | The `/tests` directory is where our PHPUnit tests are stored and makes testing a cinch, it also allows us to commit patches that include changes to both the source and the tests in a single commit. |
|---|
| 27 | |
|---|
| 28 | ### The root directory |
|---|
| 29 | |
|---|
| 30 | The `/` directory includes configuration files for our *build* tools, Travis CI and PHPUnit tests. |
|---|
| 31 | |
|---|
| 32 | ## Installing the tools |
|---|
| 33 | |
|---|
| 34 | ### Node.js |
|---|
| 35 | |
|---|
| 36 | Node.js is a platform built on Chrome's JavaScript runtime for easily building fast, scalable network applications. |
|---|
| 37 | |
|---|
| 38 | Any of the following options will get Node.js installed for you: |
|---|
| 39 | |
|---|
| 40 | * Visit [Node.js](http://nodejs.org/) and click on the *install* link to download Node.js |
|---|
| 41 | * If you're a Mac user and have [Homebrew](http://brew.sh) installed `brew install node` |
|---|
| 42 | * If you're a Windows user and have [Scoop](http://scoop.sh) installed `scoop install nodejs` |
|---|
| 43 | |
|---|
| 44 | ### Grunt |
|---|
| 45 | |
|---|
| 46 | Grunt is a JavaScript task runner to automate the tasks outlined above. |
|---|
| 47 | |
|---|
| 48 | First we need to install Grunt's command line interface (CLI). |
|---|
| 49 | |
|---|
| 50 | 1. Open a command shell terminal *You may need to use sudo (for OSX, *nix, BSD etc) or run your command shell as Administrator (for Windows)* |
|---|
| 51 | 2. Type the following into your command shell `npm install -g grunt-cli` |
|---|
| 52 | |
|---|
| 53 | ## Checking out the bbPress source |
|---|
| 54 | |
|---|
| 55 | You can use SVN or Git to contribute to bbPress, the choice is yours. so first you need to get a copy of our source |
|---|
| 56 | |
|---|
| 57 | * [Installing SVN on a Mac](https://make.wordpress.org/core/handbook/installing-a-version-control-system/installing-svn-on-a-mac/) |
|---|
| 58 | * [Installing TortoiseSVN on Windows](https://make.wordpress.org/core/handbook/installing-a-version-control-system/installing-tortoisesvn/) |
|---|
| 59 | * [Installing GitHub for Mac](https://mac.github.com/) |
|---|
| 60 | * [Installing GitHub for Windows](https://windows.github.com/) |
|---|
| 61 | |
|---|
| 62 | Once you've made that choice checkout of clone our repo If you’re fixing a bug, start by checking out bbPress' repository on your computer. |
|---|
| 63 | |
|---|
| 64 | * `svn checkout http://bbpress.svn.wordpress.org/trunk` |
|---|
| 65 | * `git clone git://bbpress.git.wordpress.org/` |
|---|
| 66 | * `git clone https://github.com/bbpress/bbPress.git` |
|---|
| 67 | |
|---|
| 68 | Note: Our GitHub mirror repo is *not* setup at this stage, soon, just not yet. See [Meta #637](https://meta.trac.wordpress.org/ticket/637) |
|---|
| 69 | |
|---|
| 70 | ## Installing Node.js dependencies with Node Package Manager (NPM) |
|---|
| 71 | |
|---|
| 72 | NPM is included with Node.js and to install the dependencies we need |
|---|
| 73 | |
|---|
| 74 | * Open up your terminal/command shell, you no longer need use sudu/admin |
|---|
| 75 | * Change to the directory where you checked out the source eg. `cd ~/dev/bbpress` |
|---|
| 76 | * Type the following into your command shell `npm install` |
|---|
| 77 | |
|---|
| 78 | ## Creating the build |
|---|
| 79 | |
|---|
| 80 | * Open up your terminal/command shell, again, you no longer need use sudu/admin |
|---|
| 81 | * Change to the directory where you checked out the source eg. `cd ~/dev/bbpress` |
|---|
| 82 | * Type the following into your command shell `grunt` |
|---|
| 83 | |
|---|
| 84 | ## Overview of the Grunt tasks we use |
|---|
| 85 | |
|---|
| 86 | ### Build tasks. |
|---|
| 87 | The default task `grunt` or `grunt build` runs the following tasks in order: |
|---|
| 88 | |
|---|
| 89 | 1. `clean:all` - Cleans and deletes the entire `/build` folder |
|---|
| 90 | 2. `copy:files` - Copies all the required files to the `/build` folder |
|---|
| 91 | 3. `colors` - Compiles our admin themes SCSS and copies the compile CSS to the `/build` folder |
|---|
| 92 | 4. `cssjanus:core` - Compiles the default CSS to RTL CSS in the `/build` folder |
|---|
| 93 | 5. `cssmin:ltr` - Minimizes the default LTR CSS in the `/build` folder |
|---|
| 94 | 6. `cssmin:rtl` - Minimizes the RTL CSS in the `/build` folder |
|---|
| 95 | 7. `uglify:core` - Minimizes the JavaScript files in the `/build` folder |
|---|
| 96 | 8. `jsvalidate:build` - Validates the JavaScript files for errors and coding best practices |
|---|
| 97 | 9. `makepot` - Generates the `bbpress.pot` file for translators |
|---|
| 98 | |
|---|
| 99 | The build release task `grunt build-release` tasks prepares everything we need to release a new version of bbPress on WordPress.org. Again the following tasks are run in order: |
|---|
| 100 | |
|---|
| 101 | 1. `clean:all` - Cleans and deletes the entire `/build` folder |
|---|
| 102 | 2. `copy:files` - Copies all the required files to the `/build` folder |
|---|
| 103 | 3. `colors` - Compiles our admin themes SCSS and copies the compile CSS to the `/build` folder |
|---|
| 104 | 4. `cssjanus:core` - Compiles the default CSS to RTL CSS in the `/build` folder |
|---|
| 105 | 5. `cssmin:ltr` - Minimizes the default LTR CSS in the `/build` folder |
|---|
| 106 | 6. `cssmin:rtl` - Minimizes the RTL CSS in the `/build` folder |
|---|
| 107 | 7. `uglify:core` - Minimizes the JavaScript files in the `/build` folder |
|---|
| 108 | 8. `jsvalidate:build` - Validates the JavaScript files for errors and coding best practices |
|---|
| 109 | 9. `checktextdomain` - Validates all of bbPress i18n text domains for internationalization |
|---|
| 110 | 10. `makepot` - Generates the `bbpress.pot` file for translators |
|---|
| 111 | 11. `phpunit` - Runs the PHPUnit tests for single site and multisite WordPress installs |
|---|
| 112 | |
|---|
| 113 | |
|---|
| 114 | ### Testing tasks. |
|---|
| 115 | |
|---|
| 116 | * `grunt phpunit` - Runs PHPUnit tests, including the ajax and multisite tests. |
|---|
| 117 | * `grunt jstest` - Runs both our javascript tasks `grunt jsvalidate` and `grunt jshint` |
|---|
| 118 | |
|---|
| 119 | |
|---|
| 120 | ### Color schemes task. |
|---|
| 121 | |
|---|
| 122 | * `grunt colors` - Compiles our admin themes SCSS and copies the compile CSS to the `/build` folder |
|---|
| 123 | |
|---|
| 124 | ### Patch task. |
|---|
| 125 | |
|---|
| 126 | * `grunt patch` - List, download and patch bbPress like a boss eg. `grunt patch:2452` |
|---|
| 127 | |
|---|
| 128 | ### Watch task |
|---|
| 129 | |
|---|
| 130 | * `grunt watch` or `grunt watch:all` Watches for file changes in the `/src` directory and automatically copy the updated file to the `/build` directory with any minification or RTL tasks included if necessary |
|---|
| 131 | |
|---|
| 132 | ## Patch All the Things! Creating and Submitting Patches |
|---|
| 133 | |
|---|
| 134 | * [WordPress Core Handbook - Working with Patches](https://make.wordpress.org/core/handbook/working-with-patches/) |
|---|
| 135 | * [WordPress Core Handbook - Working with Patches](https://make.wordpress.org/core/handbook/working-with-patches/create-a-patch-using-tortoisesvn/) |
|---|
| 136 | * [WordPress Core Handbook - Working with Patches](https://make.wordpress.org/core/handbook/working-with-patches/apply-a-patch-using-tortoisesvn/) |
|---|
| 137 | * [WordPress Core Handbook - Working with Patches](https://make.wordpress.org/core/handbook/working-with-patches/patches-with-command-line/) |
|---|
| 138 | * [WordPress Core Blog - Git mirrors - Creating a patch with Git](https://make.wordpress.org/core/2014/01/15/git-mirrors-for-wordpress/) |
|---|
| 139 | |
|---|
| 140 | ### Bug Zapping |
|---|
| 141 | |
|---|
| 142 | ## Development Best Practices for Everyone |
|---|
| 143 | |
|---|
| 144 | For best practices please refer to the information in the WordPress.org codex. You’ll find more information about [PHP](http://make.wordpress.org/core/handbook/coding-standards/php/), [HTML](http://make.wordpress.org/core/handbook/coding-standards/html/), [CSS](http://make.wordpress.org/core/handbook/coding-standards/css/) and [JavaScript](http://make.wordpress.org/core/handbook/coding-standards/javascript/) coding standards there. |
|---|