Home

This project uses an unconventional deploy process.

Please read the the Making Changes section below to ensure that you understand the process before proceeding to make changes.

Making Changes

All edits should be made in the develop branch.

The master branch is used for publishing the compiled end product. The gh-pages branch is used for QA.

1. Make sure you are able to run middleman on your system.

EXECJS_RUNTIME=Node bundle exec middleman server

If you are unable to run middleman, you will not be able to view your changes locally and builds will fail when attempting to publish.

2. Set up your remotes for QA and Production.

The scripts that publish to QA and Production use the qa and upstream remotes to publish to the respective environments.

Using these specific names for remotes are necessary in order for the scripts to run correctly.

git remote add qa https://github.com/moxiworks/moxiworks-platform.github.io

3. Make sure qa develop is not ahead of upstream develop branch.

If qa develop is ahead of upstream develop, check with committer to see if the changes are ready to be published. If they are, either the committer will need to run the publish script or you will need to pull changes from qa develop and run the publish script.

If changes are not ready to be published to Prod, you will need to make arrangements with committer to determine next steps.

4. Make sure your local develop is up to date with upstream develop branch.

5. Make your changes and preview locally.

All documents are in the partials directory.

Start middleman server to view changes locally.

EXECJS_RUNTIME=Node bundle exec middleman server

6. Commit your changes to local develop branch.

7. When ready to publish to QA, run the QA publish script

./qa_publish.sh

8. Verify changes in QA

9. When ready to publish to Production, run the Production publish script

./publish.sh

The build can take a few minutes, once complete you should see the changes in the production environment.

Viewing

Use middleman to view the documentation locally.

EXECJS_RUNTIME=Node bundle exec middleman server

Build

Middleman is used to build the documentation.

Publish scripts

qa_publish.sh and publish.sh scripts handle publishing to the respective environments.

The script is rudimentary so if you hit conflicts when merging remote develop branch when running the script, it's not going to help you out. Make sure to resolve conflicts before running the script.

Publishing Using a Pull Request

FOR REFERENCE ONLY. You should not use this method unless you fully understand the nuances of this deployment process.

[From Original Readme]

so, ideally, if you're using a pull request, your workflow could go something like:

git checkout develop

do stuff

git commit sumthin

git pull-request -b moxiworks:develop <- requires hub be installed on your system

If you're handling the other end of the PR, you'll need to merge the changes from develop into gh-pages. Your workflow could go something like:

git checkout develop

git fetch qa

git merge qa/develop

./qa_publish.sh