-
Notifications
You must be signed in to change notification settings - Fork 1
Guide for contributors
This guide is specific to contributing changes to the demo. For contributing to the library, see the library's wiki.
Similarly to the library, we use the following software for development:
- PHP 5.3: The library uses namespaces and anonymous functions!
- If you are using Windows, you'll need Windows PowerShell to run the build scripts.
- If you are using Sublime Text, the repository contains a project file with some useful settings and build systems.
- Additionally, to generate the annotated source code, we use Docco 0.6.3 which you can install via node.js.
Please refer to the library's coding conventions.
There is one addition: because we generate the documentation in the form of annotated source code from code comments, all //-style comments will appear in the documentation. However, this is no place for TODO-comments etc., so make sure to use /*...*/-style comments for anything that doesn't go in the documentation, even if it's just a single line!
With the demo we don't follow as strict a branching model as for the library. You may make small changes directly to the master branch as long as you don't push to origin before making sure the demo still works stably. For larger changes, feel free to create an arbitrary branch for your work. Or you could create a generic development branch which can be used for that purpose.
We use GitHub Pages to host the annotated source code, so we have a gh-pages branches, which contains only the docs directory. There is no need to touch this branch manually, though. See below for the relevant build scripts.
Don't ever make any changes to the library within the demo repository! Make the changes in the library repository (following its contribution guide lines) and release a new version (which may well be a pre-release version).
If a new version of the library has been released, you can update it in the demo using the build script fetch-lib.ps1 (Windows, PowerShell) or fetch-lib.sh (Unix). This will read the changes from the src-only branch in the library repository (which is kept up-to-date automatically) and merge them into the lib directory of the demo. Of course, make sure to thoroughly test the demo and apply necessary changes to make it work before pushing to master.
As mentioned above, the demo is documented in the form annotated source code. There are two build scripts to help you with that.
build-doc (with the appropriate extension for your system) simply runs Docco with the necessary parameters, and updates the files in docs. It doesn't do anything git-related - no add or commit or push or anything. Use this as often as necessary to get the documentation the way you want it.
Once the documentation is ready for publishing, commit it and, if necessary, merge it into the master branch.
Then you can use publish-doc, which will update the docs directory in the gh-pages branch based on the master branch. Note that it still won't push any branches, so once everything is done, you still need to do
git push origin gh-pages
Note: The build scripts still need to be ported to Unix. Currently, only the PowerShell scripts work. If you want to contribute to the library and are using a Unix system, please port the build scripts first or create an issue here on GitHub.