Skip to:
Content

bbPress.org

Ticket #3307: README.md

File README.md, 7.9 KB (added by netweb, 23 months ago)
Line 
1# bbPress
2
3bbPress is forum software with a twist from the creators of WordPress. Easily setup discussion forums inside your WordPress.org powered site.
4
5Have 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
7We'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
11As 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
22The `/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
26The `/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
30The `/` direcory includes configuration files for our *build* tools, Travis CI and PHPUnit tests.
31
32## Installing the tools
33
34### Node.js
35
36Node.js is a platform built on Chrome's JavaScript runtime for easily building fast, scalable network applications.
37
38Any 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 your a Mac user and have [Homebrew](http://brew.sh) installed `brew install node`
42* If your a Windows user and have [Scoop](http://scoop.sh) installed `scoop install nodejs`
43
44### Grunt
45
46Grunt is a JavaScript task runner to automate the tasks outlined above.
47
48First we need to install Grunt's command line interface (CLI).
49
501. 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)*
512. Type the following into your command shell `npm install -g grunt-cli`
52
53## Checking out the bbPress source
54
55You 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
62Once 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
68Note: 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 dependancies with Node Package Manager (NPM)
71
72NPM is included with Node.js and to install the dependancies 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.
87The default task `grunt` or `grunt build` runs the following tasks in order:
88
891. `clean:all` - Cleans and deletes the entire `/build` folder
902. `copy:files` - Copies all the required files to the `/build` folder
913. `colors` - Compiles our admin themes SCSS and copies the compile CSS to the `/build` folder
924. `cssjanus:core` - Compiles the default CSS to RTL CSS in the `/build` folder
935. `cssmin:ltr` - Minimizes the default LTR CSS in the `/build` folder
946. `cssmin:rtl` - Minimizes the RTL CSS in the `/build` folder
957. `uglify:core` - Minimizes the JavaScript files in the `/build` folder
968. `jsvalidate:build` - Validates the JavaScript files for errors and coding best practices
979. `makepot` - Generates the `bbpress.pot` file for translators
98
99The 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
1011. `clean:all` - Cleans and deletes the entire `/build` folder
1022. `copy:files` - Copies all the required files to the `/build` folder
1033. `colors` - Compiles our admin themes SCSS and copies the compile CSS to the `/build` folder
1044. `cssjanus:core` - Compiles the default CSS to RTL CSS in the `/build` folder
1055. `cssmin:ltr` - Minimizes the default LTR CSS in the `/build` folder
1066. `cssmin:rtl` - Minimizes the RTL CSS in the `/build` folder
1077. `uglify:core` - Minimizes the JavaScript files in the `/build` folder
1088. `jsvalidate:build` - Validates the JavaScript files for errors and coding best practices
1099. `checktextdomain` - Validates all of bbPress i18n text domains for internationalization
11010. `makepot` - Generates the `bbpress.pot` file for translators
11111. `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 nessecsary
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
144For 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.