Writing a Blog Post

  1. Pull down the latest website codebase for the current posts

     git pull
  2. Create a new entry in the www/_posts directory.

  3. Use an earlier post an a template. Edit your md file to remove undesired markdown links. If there is a phrase in square brackets that isn't a CB-xxxx reference, escape it with backslashes. Otherwise, heruko might error out and fail to build all the html.

     [CB-1234] \[iOS\] \[Camera\] add a whizzbang to the snarfblat
  4. Set a marker where the summary on the home page should stop displaying. Add the following html comment line to your md file at the desired cutoff point:

  5. In the front matter of your blog entry, set the date: field to the desired date that you want to appear near the title. Be aware that the date (explicit here or implied via the filename) will be used to generate the relative path to this html file (e.g. “/announcements/2014/09/22/cordova-361.html”), as will the categories: front matter value.

     date: 2014-09-22
     categories: announcements
  6. Run gulp link-bugs to linkify

     gulp link-bugs
  7. Preview it locally by running the site using gulp

  8. Raise a Pull Request with the changes

Types of Posts

Announcements - releases, call for translators, etc

Core Content - If the content has to do with cordova-core, or publishing guides, etc., we should publish the full text directly on the cordova Blog (by whichever author), as-if written by the organization.

Linked Posts - If the content was written by a contributor and is worth curating for the whole community, but is not really core ie. non-core plugins, dev tips, research, opinion-pieces, statistics, etc., post a short description, perhaps adding a document-snippet, but then link to the externally hosted content, making it clearly not written by the organization.

Post guidelines

  • Use the post title as the first header.
  • Including a header as well makes the snippet on the front page look bad.
  • Use an appropriate category:
  • One of:
    • howto
    • news
    • releases
    • announcements
    • blog (the catch-all category)
  • Use appropriate tags:
    • tools
    • plugins
    • android
    • ios
    • windowsphone
    • blackberry
    • plugin-$FOO
    • cli
    • performance
    • last-week
    • security
    • (add to this list as necessary)
  • Use gulp to preview your posts locally.
  • Jekyll does a poor job telling you where markdown errors exist.
  • Use the <!--more--> tag to specify the cutoff point for displaying your post on the main page.
  • Review your post yourself before asking for a review. This includes spell-check :).
  • Ask for a review by raising a pull request

Creating “last week” Posts

To get a summary of changes (and count the changes):

for l in cordova-*; do ( cd $l ; git log --format="$(printf %30s $l) %s" --no-merges --since='1 week ago' ) ; done | grep -iv version | grep -v CHANGELOG > all_logs.txt

To get the number of authors:

for l in cordova-*; do ( cd $l ; git log --format="%an" --no-merges --since='1 week ago' ) ; done | sort | uniq | wc -l

Creating Release Announcement Posts

Create a copy of a previous post and update it.

To print the list of plugin versions tested:

  1. Make sure all plugin repos are cloned, updated, and on master branch

  2. Run:

     for d in *-plugin-*; do ( cd $d && echo "* $(basename $PWD): $(grep version plugin.xml|grep -v encoding|cut -d'"' -f2)" ) ; done | grep '^\*'