Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

saner docs site versions #2545

Merged
merged 9 commits into from
May 29, 2018
Merged

saner docs site versions #2545

merged 9 commits into from
May 29, 2018

Conversation

giladgray
Copy link
Contributor

@giladgray giladgray commented May 24, 2018

🌐 new site layout:

blueprintjs.com/ 
    index.html - landing
    docs/
        index.html - latest docs site
        versions/
            1/, 2/, ...
                index.html - older versions

🔨 new deploy process:

# build the thing (unchanged)
yarn compile
yarn dist

# copy assets into site/ dir so it contains the entire site:
# landing, latest docs, older docs versions 
yarn site 

# push to master branch (github pages)
yarn deploy

site/ directory replaces docs-static as the only static site directory: no more git dir and a separate build dir. site/ contains the older versions (tracked in git) and yarn site (🔨 new build task) will copy the landing and docs apps into their proper places in site/ so it is ready to yarn deploy.

you can see updated links in versions menu (but they don't work on circle).

i'm going to make related PRs on 1.x and 2.x to simplify the versions/ release process
actually, PRs are not necessary! just need to update the wiki page: https://github.com/palantir/blueprint/wiki/Release-process

@giladgray
Copy link
Contributor Author

giladgray commented May 24, 2018

(for the wiki page)

Bonus: Releasing a previous major version

The main branch of this repository contains latest code. Making a 1.x or 2.x release is similar to the process above (target release/1.x instead of develop), but the docs deployment part is different:

  • Checkout release/#.x and yarn to re-install depenendencies
  • Build fresh #.x docs with yarn clean && yarn compile && yarn dist
  • Replace site/docs/versions/# on develop with the contents of packages/docs-app/dist
    • Copy packages/docs-app/dist/ outside of the repo.
    • Switch to develop, start a new branch.
    • Paste the contents of the folder you just copied into site/docs/versions/#. Replace all existing contents of the folder (there may be old files with md5-hashed names that are now dead code).
    • 🌟 If you maintain multiple clones of Blueprint (say at 1.x and 3.x) then this is very easy:
      rsync --recursive --delete packages/docs-app/dist/ ../blueprint/site/docs/versions/1
      
    • ⚠️ Do not run yarn site before committing as it will clean the site/ directory.
  • Make a PR against develop with the changes to the static assets you just made.

@blueprint-bot
Copy link

fix gitignore to actually track docs/site/versions

Preview: documentation | landing | table

Copy link
Contributor

@themadcreator themadcreator left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the new structure except two points:

  1. I feel like the git clean can be a foot cannon unless you know what you're doing. This is mitigated by the fact that this is only relevant on major releases.
  2. Releasing a new major version of docs requires a bit of careful thought and domain knowledge. This is mitigated by the release guide on the wiki

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants