Permalink
Browse files

updated README.md

  • Loading branch information...
1 parent 594993f commit 6adb6fe60329ef8848cd8be4af79c3e8836480d9 @wbamberg wbamberg committed Oct 18, 2012
Showing with 46 additions and 10 deletions.
  1. +36 −1 README.md
  2. +8 −7 docs-tools/get_releases.sh
  3. +1 −1 docs-tools/git_commit.sh
  4. +1 −1 docs-tools/make_webdocs.sh
View
@@ -30,4 +30,39 @@ To build the docs for a release use the top-level script `make_webdocs.sh`, whic
`make_webdocs.sh` takes three mandatory parameters and one optional parameter:
* the first parameter is the Git tag identifying the release destined to become the new release. It's expected to consist of number and a period, like a normal release identifier, followed by one or more alpha characters, followed by anything. For example, `"1.11rc1"` or `"1.9b2"`.
-* the second and third parameters are the version numbers for the two previous releases.
+* the second and third parameters are the version numbers for the two previous releases. They are expected to identify a particular build under `https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/` when prefixed with `addon-sdk-`.
+* the fourth, optional parameter names a file which contains a set of mappings, which map files in an obsoleted release to the corresponding file in the latest release. This is to enable the "obsoleted" notice to point users at the right file in `latest` even when the file in `latest` is in a different location.
+
+### Mappings file purpose and structure ###
+
+You don't need to define mappings for files which haven't moved relative to the docs root (for example, if "sdk/1.9/packages/addon-kit/page-mod.html" exists, and so does "sdk/1.11/packages/addon-kit/page-mod.html"), or if files have been removed in the `latest` version. You'll typically define mappings when you've reorganized the doc tree in `latest`, so the same file is now found at a different location relative to the root."
+
+Each line in the mappings file defines a mapping, and consists of the file's location in the obsolete tree, followed by a space, followed by the file's location in `latest`. For example, in 1.12 we'll be moving the API reference docs, so the file at "sdk/1.11/packages/addon-kit/page-mod.html" will be at "sdk/1.12/modules/sdk/page-mod.html". So we will include a mappings file with entries like:
+
+ sdk/1.11/packages/addon-kit/page-mod.html sdk/1.12/modules/sdk/page-mod.html
+ sdk/1.10/packages/addon-kit/page-mod.html sdk/1.12/modules/sdk/page-mod.html
+
+As you see, you can specify mapping for both obsolete releases in the mappings file. However, you can't use wildcards.
+
+### Operation of `make_webdocs.sh` ###
+
+`make_webdocs.sh` does the following:
+
+* prepares to make a new commit of the docs, by deleting everything under `sdk/`
+* fetches the latest docs from GitHub, and the two obsolete releases from `https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/`
+* generates and extracts the static docs, and copies them all under `sdk/`
+* inserts the obsolete notice in every HTML file in the obsolete releases. The logic of this is as follows: for each file in the obsolete release:
+** if a mapping exists in the mappings file, make the obsolete notice point at the target mapping file.
+** otherwise, if a file with the same name exists in the `latest` release tree, at the same relative path from the root, make the obsolete notice point at that file. For example, `"sdk/1.9/packages/addon-kit/page-mod.html"` -> `"sdk/1.11/packages/addon-kit/page-mod.html"`.
+** otherwise, make the obsolete notice point at the root file in `latest`, for example: `"sdk/1.9/packages/api-utils/message-manager.html"` -> `"sdk/1.11/"`. In this case, different wording is used to indicate that the file is missing in `latest`, and the file is listed in the console output: this is intended to help you realise if you forgot to include a mapping for a file that was moved.
+* add everything under `sdk/` to Git's staging area, commit it, and tag the commit with the Git tag identifying the latest release suffixed with "-amo": for example, `"1.11rc1-amo"`
+
+### What to do next ###
+
+After running `make_webdocs.sh` check that the contents of `sdk/` is what you expect, in particular that the obsolete docs contain obsolete notices, and that the links these notices contain are good.
+
+If everything looks all right, push the changes to GitHub:
+
+ git push --tags origin master
+
+Then ask IT to copy the content of `sdk/` at the relevant tag to `addons.mozilla.org`.
View
@@ -1,10 +1,13 @@
-mkdir sdk/$1
+pos=$(expr $1 : '[0-9,\.]*')
+latest_version=${1:0:$pos}
+
+mkdir sdk/$latest_version
mkdir sdk/$2
mkdir sdk/$3
mkdir working
cd working
-mkdir $1
+mkdir $latest_version
mkdir $2
mkdir $3
@@ -21,16 +24,14 @@ function get_release {
}
# get the latest release
-cd $1
+cd $latest_version
git clone https://github.com/mozilla/addon-sdk.git
cd addon-sdk
git checkout $1
source bin/activate
-pos=$(expr $1 : '[0-9,\.]*')
-echo ${1:0:$pos}
-cfx sdocs --override-version=$1
+cfx sdocs --override-version=$latest_version
tar -xf addon-sdk-docs.tgz
-mv doc/* ../../../sdk/$1
+mv doc/* ../../../sdk/$latest_version
cd ../../
get_release $2
View
@@ -1,3 +1,3 @@
git add sdk/*
git commit -m "add $1 docset"
-git tag -a (CANDIDATE VERSION)-amo -m "tagged $1 docset"
+git tag -a $1-amo -m "tagged $1 docset"
@@ -18,4 +18,4 @@ python obsolete.py $old_version1 $latest_version $4
python obsolete.py $old_version2 $latest_version $4
# make the commit
-#bash git_commit.sh
+bash git_commit.sh $1

0 comments on commit 6adb6fe

Please sign in to comment.