My favorites | Sign in
Project Home
Search
for
ContributorsGuide  
Updated Apr 23, 2012 by ericbide...@html5rocks.com

Step-by-step guide for third-party developers to contribute to html5rocks.com. Before you draft the article, read the writing tips.

Before you start

HTML5Rocks runs on Google App Engine (Python). Before you check out the code, download the App Engine Python SDK. The SDK is not required, but highly recommended. You'll want to run a local development server and preview your changes before submitting a tutorial, sample, or patch.

Our code repository is Git. If you do not have it, download and install it.

Getting the code

The entirety of HTML5Rocks (www, studio, slides, playground, updates) is located here.

Each sub-domain points to a separate Google App Engine (Python) application with a corresponding sub-directory in the src tree:

Sub-domain App ID src
www.html5rocks.com http://html5rocks.appspot.com /www.html5rocks.com
studio.html5rocks.com http://html5playbook.appspot.com /studio.html5rocks.com
slides.html5rocks.com http://html5slides.appspot.com /slides.html5rocks.com
playground.html5rocks.com http://html5playground.appspot.com /playground.html5rocks.com
updates.html5rocks.com http://updaterocker.appspot.com /updates.html5rocks.com

To checkout the src, run the following command:

git clone https://code.google.com/p/html5rocks/

Contributing: submitting patches and tutorials

Submitting a code patch, studio/playground sample

Contributor License Agreements

This section only applies if you are submitting a patch for us. The CLA mentioned below does not apply if you are giving us a brand new article or tutorial.

We'd love to accept your code patches! However, before we can take them, we have to jump a couple of legal hurdles.

Please fill out either the individual or corporate Contributor License Agreement.

  • If you are an individual writing original source code and you're sure you own the intellectual property, then you'll need to sign an individual CLA.
  • If you work for a company that wants to allow you to contribute your work to HTML5Rocks.com, then you'll need to sign a corporate CLA.

Follow either of the two links above to access the appropriate CLA and instructions for how to sign and return it. Once we receive it, we'll add you to the official list of contributors and be able to accept your patches.

  1. Sign the contributors license agreement above.
  2. Decide which code you want to submit. A submission should be a set of changes that addresses one issue in the HTML5Rocks issue tracker. Please don't mix more than one logical change per submittal, because it makes the history hard to follow. If you want to make a change (e.g. add a sample or feature) that doesn't have a corresponding issue in the issue tracker, please create one.
  3. Submitting: When you are ready to submit, attach a diff of your patch (by running git diff /path/to/file) to the issue.

Writing a tutorial / case study

  • Our articles and case studies are licensed under Creative Commons Attribution 3.0 License. Be sure you are OK with that.
  • If one doesn't already exist, Create a new issue in the issue tracker so others can follow/comment on progress.

Now choose your adventure:

Semi-automated process

The main project folder contains a script, www.html5rocks.com/scripts/generate_tutorial.py to automate the creation of new tutorials/case studies. It does this by:

  1. Creating the directory and file you pass in via the command line. The article's templates is taken from www.html5rocks.com/content/tutorials/tutorial.html.template.
  2. Prompting you for various information (article title, name, tags, etc.)
  3. Adding your article to the /tutorials/index.html

To create a new tutorial run:

  cd www.html5rocks.com/
  python scripts/generate_tutorial.py --output /file/filesystem/index.html

where the --output parameter is of the form: /<api_name>/<tutorial_name>/index.html

To create a new case study run:

  cd www.html5rocks.com/scripts
  python generate_tutorial.py --output /casestudies/company_articlename.html

To create a mobile article:

  cd www.html5rocks.com/scripts
  python generate_tutorial.py --output /mobile/articlename.html

If you have an existing .txt file containing article content (or a Google Doc exported to .txt), the script can take an --input parameter that will populate the empty article with your content:

  cd www.html5rocks.com/scripts
  python generate_tutorial.py --output /casestudies/company_articlename.html --input ~/path/to/content.txt

Note: You'll need to still clean up the generated HTML in company_articlename.html.

This script tries to mimic the manual process (below) but isn't perfect. Some HTML clean up/formatting will be necessary. For example, you still need to replace the ___COMPAT_TEST___ in your generated article with an appropriate Modernizr (or raw JS) test that makes sense for your article, add a summary description in `/tutorials/index.html', and other other loose ends.

If you are a new author, add yourself to www.html5rocks.com/profiles.yaml. We'll also need a .png photo of you for the profiles page.

Manual process

  1. If you are a new author, add yourself to www.html5rocks.com/profiles.yaml. We'll also need a .png photo of you for the profiles page.
  2. Add a new directory for your tutorial/case study. Both are located in http://code.google.com/p/html5rocks/source/browse/#git%2Fwww.html5rocks.com%2Fcontent%2Ftutorials<api_name>/<tutorial_name> and are hosted under the live site at http://www.html5rocks.com/tutorials/. Please use good judgement when naming a new directory/tutorial. HTML files will automatically be parsed by the templating system, which is Django based. See Django template tags and filters for more information.
  3. If you're writing a case study, add your article under /content/tutorials/casestudies/ instead. The naming convention is company_articlename.html.
  4. Copy www.html5rocks.com/content/tutorials/tutorial.html.template to your directory and replace its holder variable ___COMPAT_TEST___ your our feature detect. Also remove the html comment at the top, otherwise you'll get parsing errors.
  5. Add your article to the /tutorials.yaml file.

Modify a previous entry to match the details of your tutorial. When possible, try to use existent tags. If you're writing a case study, be sure to tag the article with the type:casestudy tag.

Writing/Augmenting a feature page

  1. URL like http://www.html5rocks.com/features/offline uses a file in content/features/offline.html
  2. New files should be created using what's in feature_empty.html of that same directory. It has a useful markup skeleton that'll save you time.

Submitting: When you are ready to submit, attach a diff of your patch (by running git diff /path/to/file) to the issue.

i18n

A few things to note about internationalization:

  1. All templates need to include the i18n library by adding {% include 'i18n' %} as early as possible.
  2. UI strings must be wrapped with {% blocktrans %} or {% trans ... %} tags. These are well explained in http://docs.djangoproject.com/en/1.2/topics/i18n/.
  3. Articles live one subdirectory deeper to encode their locale, in http://code.google.com/p/html5rocks/source/browse/www.html5rocks.com/content/tutorials/3d/css/en/index.html?r=v4 for example.
  4. Similarly, all case studies live in http://code.google.com/p/html5rocks/source/browse/www.html5rocks.com/content/tutorials/casestudies/en
Comment by raymondc...@gmail.com, Apr 10, 2012

Can you please explain how we runt he site? I've got it checked out. I've got an Apache Virtual Host set up for it. But hitting any of the files with template tokens shows the tokens not being processed.

Comment by raymondc...@gmail.com, Apr 10, 2012

In order to get this running, I had to go to the folder where I cloned the site, and do this at the command line dev_appserver.py www.html5rocks.com.

Comment by raymondc...@gmail.com, Apr 10, 2012

I believe section 5 is obsolete. There does not appear to be <article> blocks anymore.

Comment by raymondc...@gmail.com, Apr 10, 2012

After running - I still am not able to test. Hitting the main tutorials page shows no tutorials - just a basic layout. Hitting the actual page I made creates a page load of errors.

Comment by yauriedogawa, Apr 25, 2012

How to participate for translation? I want to help with Indonesian version

Comment by project member mkwst@google.com, May 2, 2012

Hi yauriedogawa! If you'd like to help translate the site, take a look at the LocalizationGuide. That should give you the detail you need to get started.

Comment by juliano....@gmail.com, May 22, 2012

Hi Guys,

I am having the same problem of @raymondc. Per some reason the yaml files are not being parsed. Is this something related with the dependencies?

Thanks

Comment by project member paulir...@google.com, Jun 7, 2012

@juliano: I hit this URL http://localhost:8080/database/load_all and log in as admin. It populates a temp database based on whats in the yaml.

Comment by tono...@gmail.com, Jun 17, 2012

Proszę powiedzcie drodzy naukowcy co porabiał Klamm w Zamku Franza Kafki? Za friko, za naukę nie kasuję.

Comment by tono...@gmail.com, Jun 17, 2012

Na marginesie wiki nie unie pisać i nie ma tym samym składni. To zlepki wstrząśnięte nie zmieszane.

Comment by funkyharsh001, Jun 21, 2012

what is the command for cloning html5rocks?


Sign in to add a comment
Powered by Google Project Hosting