-
Notifications
You must be signed in to change notification settings - Fork 554
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Move instructions about blogposts, redirects and adding tools or show…
…case apps to individial files in /doc (Only minimal changes to actual instructions) This closes #737
- Loading branch information
Showing
4 changed files
with
189 additions
and
170 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,87 @@ | ||
| # Writing a Blog Post | ||
|
|
||
| 1. Pull down the latest website codebase for the current posts | ||
|
|
||
| git pull | ||
|
|
||
| 1. Create a new entry in the www/_posts directory. | ||
|
|
||
| 1. 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 | ||
|
|
||
| 1. 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: | ||
|
|
||
| <!--more--> | ||
|
|
||
| 1. 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 | ||
|
|
||
| 1. Run gulp link-bugs to linkify | ||
|
|
||
| gulp link-bugs | ||
|
|
||
| 1. Preview it locally by running the site using gulp | ||
|
|
||
| 1. 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 '^\*' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| # Redirects | ||
|
|
||
| Sometimes (docs) pages get removed, renamed, and added. There is [a redirects file](../www/_data/redirects.yml) that contains redirects for such occasions. It has three sections: | ||
|
|
||
| - `general`: single-page redirects, | ||
| - `docs-global`: redirects across all docs versions and languages, and | ||
| - `docs`: version-specific docs redirects. | ||
|
|
||
| For non-docs URIs, there are no versioning considerations. Make redirects like so: | ||
|
|
||
| general: | ||
| - {old: "old/uri/for/page.html", new: "its/new/uri.html"} | ||
|
|
||
| **NOTE**: Review (and test, if possible) these redirects before making them live, since they're permanent (HTTP 301) redirects. Incorrect permanent redirects will make a URI almost impossible to bring back into browsers and search indices. | ||
|
|
||
| ## Changing Docs URIs | ||
|
|
||
| There are five cases of changing URIs: | ||
|
|
||
| 1. Adding a brand new (no past equivalent) URI starting at a version, | ||
| 2. Removing an old URI (with no replacement) starting at a version, | ||
| 3. Renaming (removing and adding) an existing URI starting at a version, | ||
| 4. Renaming an existing URI across all versions, | ||
| 5. Removing an existing URI across all versions. | ||
|
|
||
| ### Case 1: Adding a URI starting at a version | ||
|
|
||
| Do nothing. Going back in time for new docs is unsupported. | ||
|
|
||
| ### Cases 2 & 3: Removing or renaming a URI starting at a version | ||
|
|
||
| If the URI is removed, mark it as deprecated in `latest/` like so: | ||
|
|
||
| docs: | ||
| - {old: "latest/old/uri/for/page.html", new: "deprecated.html"} | ||
|
|
||
| If the URI is moved, point it to its new location in `latest/` like so: | ||
|
|
||
| docs: | ||
| - {old: "latest/old/uri/for/page.html", new: "latest/its/new/uri.html"} | ||
|
|
||
| These will handle the case where the "this content is outdated" link is clicked. The case where a user jumps to a specific version is not yet supported. | ||
|
|
||
| ### Case 4: Renaming a URI across all versions | ||
|
|
||
| Add the redirect (in the `docs-global` section this time) like so: | ||
|
|
||
| docs-global: | ||
| - {old: "old/uri/for/page.html", new: "its/new/uri.html"} | ||
|
|
||
| ### Case 5: Removing a URI across all versions | ||
|
|
||
| Do nothing. It is now an un-URI. It never existed. Mentioning it is thoughtcrime. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| # Adding a Tool or a Showcase App | ||
|
|
||
| Items on the **Codorva Tools** or the **Cordova App Showcase** sections on the main page are modifiable by the public. Below are the guidelines and process to do so. | ||
|
|
||
| ## Guidelines | ||
|
|
||
| The display _image_ shall: | ||
|
|
||
| 1. be __less than 128KiB__ in size (NOTE: those are kibibytes, not kilobytes), | ||
| 2. contain the __logo__ of the tool/app, | ||
| 3. use __colors that don't compete__ with other elements on the page, and | ||
| 4. have acceptable measurements, as follows: | ||
| - __298px by 100px__ or smaller with a roughly rectangular aspect ratio for tools, and | ||
| - __100px by 100px__ or smaller with a square aspect ratio for apps. | ||
|
|
||
| The _description_ shall: | ||
|
|
||
| 1. contain __neutral__ and non-advertising language. | ||
|
|
||
| The _name_ shall: | ||
|
|
||
| 1. be __at most 40__ characters long. | ||
|
|
||
| Showcase _apps_ shall: | ||
|
|
||
| 1. be available for download on a __public app store__ or website. | ||
|
|
||
| Furthermore, descriptions are stripped of HTML and are truncated to fit as follows: | ||
|
|
||
| - down to 255 characters for tools and, | ||
| - down to 200 characters for showcase apps. | ||
|
|
||
| ## Process | ||
|
|
||
| 1. Change the section's YAML file: | ||
| - [www/_data/tools.yml](../www/_data/tools.yml) for Cordova Tools, or | ||
| - [www/_data/showcase-apps.yml](../www/_data/showcase-apps.yml) for Cordova App Showcase. | ||
| 1. Optionally add an image: | ||
| 1. Place the image in the section's `img` directory: | ||
| - [www/static/img/tools](../www/static/img/tools) for Cordova Tools, or | ||
| - [www/static/img/showcase-apps](../www/static/img/showcase-apps) for Cordova App Showcase. | ||
| 1. In the YAML file, set the `image` field to the file's *name*. | ||
| 1. Submit a [GitHub pull request][pr] with the changes. | ||
|
|
||
| [pr]: https://help.github.com/articles/using-pull-requests/ |