Mailing-List: contact commits-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: audreyso@apache.org
To: commits@cordova.apache.org
Message-Id: <5b597d97ddb742cd80fdf5d2f59c162d@git.apache.org>
Subject: docs commit: Move instructions about blogposts,
 redirects and adding tools or showcase apps to individial files in
 /doc (Only minimal changes to actual instructions)
Date: Thu, 28 Sep 2017 19:54:10 +0000 (UTC)
archived-at: Thu, 28 Sep 2017 19:54:14 -0000

Repository: cordova-docs
Updated Branches:
  refs/heads/master b64f20fe1 -> c0e235764


Move instructions about blogposts, redirects and adding tools or showcase apps to individial files in /doc
(Only minimal changes to actual instructions)

 This closes #737


Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/c0e23576
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/c0e23576
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/c0e23576

Branch: refs/heads/master
Commit: c0e23576425bf5f5be2c647c88f6eb9c7cb6c55f
Parents: b64f20f
Author: Jan Piotrowski <piotrowski@gmail.com>
Authored: Tue Sep 26 15:27:41 2017 +0200
Committer: Audrey So <audreyso@apache.org>
Committed: Thu Sep 28 12:53:33 2017 -0700

----------------------------------------------------------------------
 README.md                   | 174 +--------------------------------------
 doc/blogpost.md             |  87 ++++++++++++++++++++
 doc/redirects.md            |  53 ++++++++++++
 doc/tool-or-showcase-app.md |  45 ++++++++++
 4 files changed, 189 insertions(+), 170 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c0e23576/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index bcf9ce0..a9b5fff 100644
--- a/README.md
+++ b/README.md
@@ -34,20 +34,10 @@ This repository contains the source code for the Cordova website. This covers [c
   * [Building](#building)
   * [Developing](#developing)
     + [Docs Redirects](#docs-redirects)
-      - [Case 1: Adding a URI starting at a version](#case-1-adding-a-uri-starting-at-a-version)
-      - [Cases 2 &amp; 3: Removing or renaming a URI starting at a version](#cases-2--3-removing-or-renaming-a-uri-starting-at-a-version)
-      - [Case 4: Renaming a URI across all versions](#case-4-renaming-a-uri-across-all-versions)
-      - [Case 5: Removing a URI across all versions](#case-5-removing-a-uri-across-all-versions)
   * [Deploying](#deploying)
   * [Working on the Documentation](#working-on-the-documentation)
   * [Adding a Tool or a Showcase App](#adding-a-tool-or-a-showcase-app)
-    + [Guidelines](#guidelines)
-    + [Process](#process)
   * [Writing a Blog Post](#writing-a-blog-post)
-    + [Types of Posts](#types-of-posts)
-    + [Post guidelines](#post-guidelines)
-    + [Creating "last week" Posts](#creating-last-week-posts)
-    + [Creating Release Announcement Posts](#creating-release-announcement-posts)
   * [Troubleshooting](#troubleshooting)
     + [Error: EMF, too many open files](#error-emf-too-many-open-files)
     + [Error: spawn ENOENT](#error-spawn-enoent)
@@ -212,55 +202,7 @@ Alternatively, to dynamically rebuild the site and refresh the browser _when cha
 
 ### Docs Redirects
 
-Sometimes docs pages get removed, renamed, and added. There is [a file][redirects] that contains redirects for such occasions. It has three sections:
-
-- `docs-global`: redirects across all docs versions and languages,
-- `docs`: version-specific docs redirects, and
-- `general`: single-page 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.
-
-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 &amp; 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.
+See [doc/redirects.md](doc/redirects.md).
 
 ## Deploying
 
@@ -298,125 +240,17 @@ Once you are satisfied that you have added the required changes, commit with a m
 
 ## Working on the Documentation
 
-Refer to this [README.md](doc/README/en/README.md) for information about writing documentation.
+Refer to [doc/README/en/README.md](doc/README/en/README.md) for information about writing documentation.
 
 > Note: many changes to the overall documentation come from other repos and are simply pulled together by a build.  tools/bin/fetch_docs.js has more details and www/_data/fetched-files.yml contains an informative list of src/dest pairs.  Most auto-generated files have a comment tag at the top of the file to indicate that they come from elsewhere.
 
 ## 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.
+See [doc/tool-or-showcase.md](doc/tool-or-showcase-app.md).
 
 ## 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:
-
-        <!--more-->
-
-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 '^\*'
+See [doc/blogpost.md](doc/blogpost.md).
 
 ## Troubleshooting
 

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c0e23576/doc/blogpost.md
----------------------------------------------------------------------
diff --git a/doc/blogpost.md b/doc/blogpost.md
new file mode 100644
index 0000000..d2528d6
--- /dev/null
+++ b/doc/blogpost.md
@@ -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 '^\*'
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c0e23576/doc/redirects.md
----------------------------------------------------------------------
diff --git a/doc/redirects.md b/doc/redirects.md
new file mode 100644
index 0000000..d4cdcef
--- /dev/null
+++ b/doc/redirects.md
@@ -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 &amp; 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.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c0e23576/doc/tool-or-showcase-app.md
----------------------------------------------------------------------
diff --git a/doc/tool-or-showcase-app.md b/doc/tool-or-showcase-app.md
new file mode 100644
index 0000000..ead8bc3
--- /dev/null
+++ b/doc/tool-or-showcase-app.md
@@ -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/


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org