Move deploys under a version namespace

Author: dfreeman

lib/config.js

@@ -22,7 +22,8 @@ module.exports = class AddonDocsConfig {
     }
 
     if (this.repoInfo.tag) {
-      return this.repoInfo.tag;
+      // Turn v1.0.0 -> 1.0.0 since we're prefixing with /v/
+      return this.repoInfo.tag.replace(/^v(\d)/i, '$1');
     }
 
     return this.repoInfo.branch || process.env.TRAVIS_BRANCH;
@@ -33,7 +34,7 @@ module.exports = class AddonDocsConfig {
       return process.env.ADDON_DOCS_VERSION_NAME;
     }
 
-    return this.getVersionPath();
+    return this.repoInfo.tag || this.repoInfo.branch || process.env.TRAVIS_BRANCH;
   }
 
   shouldUpdateLatest() {

lib/deploy/plugin.js

@@ -6,6 +6,8 @@ const execa = require('execa');
 const quickTemp = require('quick-temp');
 const hostedGitInfo = require('hosted-git-info');
 
+const VERSION_PREFIX = 'v';
+
 module.exports = class AddonDocsDeployPlugin {
   constructor(userConfig) {
     this.name = 'addon-docs';
@@ -42,6 +44,8 @@ module.exports = class AddonDocsDeployPlugin {
     let stagingDirectory = context.addonDocs.stagingDirectory;
     let fullBuildDestination = path.join(stagingDirectory, relativeBuildDestination);
 
+    fs.ensureDirSync(fullBuildDestination);
+
     return this._copyExistingFiles(context, relativeBuildDestination)
       .then(() => this._copyBuildOutput(context, stagingDirectory, relativeBuildDestination))
       .then(() => this._verifyRootFiles(stagingDirectory))
@@ -54,8 +58,8 @@ module.exports = class AddonDocsDeployPlugin {
     quickTemp.remove(this, 'deployStagingDirectory');
   }
 
-  _getVersionPath(version) {
-    return version || this.userConfig.getVersionPath();
+  _getVersionPath(version = this.userConfig.getVersionPath()) {
+    return `${VERSION_PREFIX}/${version}`;
   }
 
   _verifyRootFiles(stagingDirectory) {
@@ -65,7 +69,7 @@ module.exports = class AddonDocsDeployPlugin {
       fs.copySync(`${vendorDir}/index.html`, `${stagingDirectory}/index.html`);
     }
 
-    let segmentCount = this._getRootURL().split('/').length + 1;
+    let segmentCount = this._getRootURL().split('/').length + 2;
     let redirectContents = fs.readFileSync(`${vendorDir}/404.html`, 'utf-8');
     redirectContents = redirectContents.replace(/\bADDON_DOCS_SEGMENT_COUNT\b/g, segmentCount);
     fs.writeFileSync(`${stagingDirectory}/404.html`, redirectContents);

tests/dummy/app/pods/docs/deploying/template.md

@@ -21,38 +21,39 @@ Now take a look at the `gh-pages` branch either locally or on GitHub. You should
 ```sh
 ├── 404.html
 ├── index.html
-├── [current-branch]
-│   ├── assets
-│   ├── index.html
-│   └── ...
+├── v
+│   └── [current-branch]
+│       ├── assets
+│       ├── index.html
+│       └── ...
 └── versions.json
 ```
 
 Let's break down what each of those items is doing.
- - `index.html` simply redirects from the root of your gh-pages site to `/latest` (more details on that [below](#tag-deploys))
+ - `index.html` simply redirects from the root of your gh-pages site to `/v/latest` (more details on that [below](#tag-deploys))
  - `404.html` contains [some smart redirect logic](https://github.com/rafrex/spa-github-pages) to keep you from having to use `locationType: 'hash'` in your dummy app
  - `versions.json` contains a manifest of the available versions of your documentation
- - `[current-branch]` contains all the files from your built docs app
+ - `v/[current-branch]` contains all the files from your built docs app
 
-If you were to make a change to your dummy app and run `ember deploy production` again right now, the entry for `[current-branch]` in `version.json` and the entire contents of the `[current-branch]` directory would be replaced with the updated version of your site. Next we'll talk about how to manage keeping published documentation around for multiple versions of your addon.
+If you were to make a change to your dummy app and run `ember deploy production` again right now, the entry for `[current-branch]` in `version.json` and the entire contents of the `v/[current-branch]` directory would be replaced with the updated version of your site. Next we'll talk about how to manage keeping published documentation around for multiple versions of your addon.
 
 ## Versioning your content
 
 Whenever you deploy your documentation site with Addon Docs, it places the compiled application in a subdirectory based on the current state of your git repository. All of this behavior [is customizable](#customizing-deploys), but we expect the out-of-the-box configuration should be a good place to get started.
 
 ### Tag deploys
 
-When you run `ember deploy` at a commit that has a git tag associated with it, the app will wind up in a directory named after that tag. For example, if you've just published version 1.2.3 of your addon (creating tag `v1.2.3` in your git repository), your deployed site will be available at <u>https://**[user]**.github.io/**[repo]**/v1.2.3</u>.
+When you run `ember deploy` at a commit that has a git tag associated with it, the app will wind up in a directory named after that tag. For example, if you've just published version 1.2.3 of your addon (creating tag `v1.2.3` in your git repository), your deployed site will be available at <u>https://**[user]**.github.io/**[repo]**/v/1.2.3</u>.
 
-By default, deploying from a tagged commit also places a copy of your app under a special directory called `/latest`. As mentioned above, the `index.html` that Addon Docs sets up at the root redirects to `/latest`, so <u>https://**[user]**.github.io/**[repo]**</u> will always bring developers to the documentation for the most recent stable release of your addon.
+By default, deploying from a tagged commit also places a copy of your app under a special directory called `/v/latest`. As mentioned above, the `index.html` that Addon Docs sets up at the root redirects to `/v/latest`, so <u>https://**[user]**.github.io/**[repo]**</u> will always bring developers to the documentation for the most recent stable release of your addon.
 
-Note that this only applies to non-prerelease tags, so `v1.2.3` would update `/latest`, but `v2.0.0-beta.1` would not. Check out the documentation for [node-semver](https://github.com/npm/node-semver) for the exact details on what constitutes a prerelease version.
+Note that this only applies to non-prerelease tags, so `v1.2.3` would update `/v/latest`, but `v2.0.0-beta.1` would not. Check out the documentation for [node-semver](https://github.com/npm/node-semver) for the exact details on what constitutes a prerelease version.
 
 ### Branch deploys
 
-When you deploy from a commit at the head of a branch that _doesn't_ have a tag associated with it, the compiled app will land in a folder named after that branch, as in our "getting started" example above. Unlike tag deploys, branch deploys will never automatically update `/latest`.
+When you deploy from a commit at the head of a branch that _doesn't_ have a tag associated with it, the compiled app will land in a folder named after that branch, as in our "getting started" example above. Unlike tag deploys, branch deploys will never automatically update `/v/latest`.
 
-The main use case for branch deploys is tracking development work since your last stable release. If you run `ember deploy` after successful builds on `master`, you'll always have documentation available for the bleeding edge of your addon's features. Since branch deploys don't update `/latest`, though, developers looking at your docs will still hit your most recent stable tag by default, so there won't be any confusion about things that have drifted since the last release.
+The main use case for branch deploys is tracking development work since your last stable release. If you run `ember deploy` after successful builds on `master`, you'll always have documentation available for the bleeding edge of your addon's features. Since branch deploys don't update `/v/latest`, though, developers looking at your docs will still hit your most recent stable tag by default, so there won't be any confusion about things that have drifted since the last release.
 
 ## Automating deploys
 
@@ -121,19 +122,19 @@ You can override methods on this class to customize deploy behavior.
 
 ### `getVersionPath()`
 
-This method determines the location that a given version of your documentation will be written to on your deploy branch.
+This method determines the location that a given version of your documentation will be written to within the `v` directory on your deploy branch.
 
-By default, this method will use the current tag name (if any), or fall back to the current branch name as described above. Note that you can override this behavior by setting an `ADDON_DOCS_VERSION_PATH` environment variable.
+By default, this method will use the current tag name (if any) stripped of its leading `v`, or fall back to the current branch name as described above. Note that you can override this behavior by setting an `ADDON_DOCS_VERSION_PATH` environment variable.
 
 If this method returns a falsey value, the deploy will be aborted.
 
 ### `getVersionName()`
 
-This method returns a name for a given version of your documentation. By default it just returns the same thing as `getVersionPath()`, but if, for instance, you wanted to set up named releases, you might override this method. You can also explicitly specify the version name by setting an `ADDON_DOCS_VERSION_NAME` environment variable.
+This method returns a name for a given version of your documentation. By default it returns the current tag if any, or the current branch name otherwise. If, for instance, you wanted to set up named releases, you might override this method. You can also explicitly specify the version name by setting an `ADDON_DOCS_VERSION_NAME` environment variable.
 
 ### `shouldUpdateLatest()`
 
-This method determines whether the `/latest` directory will also be updated with the current deploy. By default, this will return true for builds from a tagged commit where the tag is a [semver non-prerelease version](https://github.com/npm/node-semver), and false otherwise. You can explicitly set the `ADDON_DOCS_UPDATE_LATEST` environment variable to `true` or `false` to override this behavior.
+This method determines whether the `/v/latest` directory will also be updated with the current deploy. By default, this will return true for builds from a tagged commit where the tag is a [semver non-prerelease version](https://github.com/npm/node-semver), and false otherwise. You can explicitly set the `ADDON_DOCS_UPDATE_LATEST` environment variable to `true` or `false` to override this behavior.
 
 ### `getRootURL()`
 
@@ -149,15 +150,15 @@ Deploying a version of your documentation does two things: it copies the `dist`
 
 First, you can run `git checkout gh-pages` to switch to your deploy branch. You may see a message indicating that that branch has already been checked out somewhere else by `git worktree`—if that's the case, you can just `cd` to that directory instead.
 
-Next, remove the item from `versions.json` for the version you want to get rid of, and delete the corresponding directory. For example, if you ran a deploy on a branch called `deploy-test` and wanted to remove the results of that after you finished testing it out, you could `git rm deploy-test` to remove the deployed app, and then find the `deploy-test` key in `versions.json` and remove it:
+Next, remove the item from `versions.json` for the version you want to get rid of, and delete the corresponding directory. For example, if you ran a deploy on a branch called `deploy-test` and wanted to remove the results of that after you finished testing it out, you could `git rm v/deploy-test` to remove the deployed app, and then find the `deploy-test` key in `versions.json` and remove it:
 
 ```js
 {
   // ...
   "deploy-test": {
     "sha": "caad536c48dd3562629a4f7a467c976f0ec6bb2b",
     "tag": null,
-    "path": "deploy-test",
+    "path": "v/deploy-test",
     "name": "deploy-test"
   },
   // ...

vendor/ember-cli-addon-docs/index.html

@@ -4,7 +4,7 @@
     <meta charset="utf-8">
     <title>Latest Docs Redirect</title>
     <script type="text/javascript">
-      window.location.href = './latest';
+      window.location.href = './v/latest';
     </script>
   </head>
   <body>