Cloning the manubot/rootstock repository to create a new manuscript
The process to create a new Manubot manuscript is a bit challenging, because it requires a few steps that are difficult to automate. However, you will only have to perform these steps once for each manuscript. These steps should be performed in a terminal, starting in the directory where you want the manuscript folder be created. Setup is supported on Linux and macOS, but not on Windows.
First, you must configure two environment variables (
These variables specify the GitHub repository for the manuscript (i.e.
Make sure that the case of
OWNER matches how your username is displayed on GitHub.
In general, assume that all commands in this setup are case-sensitive.
Edit the following commands with your manuscript's information:
# GitHub username (change from manubot) OWNER=manubot # Repository name (change from rootstock) REPO=rootstock
Execute the remaining commands verbatim. They do not need to be edited (if the setup works as intended).
Next you must clone
manubot/rootstock and configure its branches and remotes:
# Clone manubot/rootstock git clone https://github.com/manubot/rootstock.git $REPO cd $REPO # Configure remotes and branches git remote add rootstock https://github.com/manubot/rootstock.git git checkout --orphan gh-pages git rm -r --force . git commit --allow-empty \ --message "Initialize empty branch" \ --message "[ci skip]" git checkout -b output git checkout master # Option A: Set origin URL using its web address git remote set-url origin https://github.com/$OWNER/$REPO.git # Option B: If GitHub SSH key access is enabled for OWNER, run the following command instead git remote set-url origin firstname.lastname@example.org:$OWNER/$REPO.git
Next, you must manually create an empty GitHub repository at https://github.com/new. Make sure to use the same "Owner" and "Repository name" specified above. Do not initialize the repository, other than optionally adding a Description. Next, push your cloned manuscript:
git push --set-upstream origin master git push --set-upstream origin gh-pages git push --set-upstream origin output
Now you must manually enable Travis CI for the new repository at https://travis-ci.com.
+ sign to "Add New Repository".
If you don't see your repository listed, push the "Sync account" button.
Finally, flick the repository's switch to enable CI.
Generate a deploy key so Travis CI can write to the repository.
cd ci ssh-keygen \ -t rsa \ -b 4096 \ -C "email@example.com" \ -N "" \ -f deploy.key # For convenience, print the URL to add the public key to GitHub echo https://github.com/$OWNER/$REPO/settings/keys
Manually add the text of
deploy.key.pub (with write access) to GitHub under the repository's deploy key settings (the URL echoed above).
Give the key a descriptive title, such as "Travis CI Manubot".
For the next step, you need the Travis command line client installed.
This program is a Ruby gem:
install it with
gem install travis (not
apt install travis, which is a different program).
After the install, you will need to provide your credentials to login to travis with
travis encrypt-file \ --com \ --repo=$OWNER/$REPO \ --force \ deploy.key > travis-encrypt-file.log
ci/travis-encrypt-file.log will contain a line such as:
openssl aes-256-cbc -K $encrypted_8cc93e35fb85_key -iv $encrypted_8cc93e35fb85_iv -in test.key.enc -out test.key -d
ci/deploy.sh must be updated with the random string from this line (i.e.
The following command automates this substitution.
# Edit ci/deploy.sh with travis secure env variables generated by travis encrypt-file TRAVIS_ENCRYPT_ID=`python -c "import re; \ text = open('travis-encrypt-file.log').read(); \ print(re.search('encrypted_([a-f0-9]+)_key', text).group(1))"` sed "s/9befd6eddffe/$TRAVIS_ENCRYPT_ID/g" deploy.sh > tmp && mv -f tmp deploy.sh
Next, limit concurrent Travis CI jobs to ensure previous builds deploy before subsequent ones begin:
travis settings \ --com \ --repo=$OWNER/$REPO \ maximum_number_of_builds --set 1
The continuous integration configuration is now complete. Clean up:
# Optionally remove untracked files rm deploy.key rm travis-encrypt-file.log # CRITICAL: navigate back to the repository's root directory cd ..
README.md files to reference the new repository:
# Perform substitutions sed "s/manubot\/rootstock/$OWNER\/$REPO/g" README.md > tmp && mv -f tmp README.md sed "s/manubot\.github\.io\/rootstock/$OWNER\.github\.io\/$REPO/g" README.md > tmp && mv -f tmp README.md # Remove deletable content file git rm content/02.delete-me.md
git status or
git diff --color-words to check that the following files have unstaged changes:
If the changes look okay, commit and push:
git add --update git commit --message "Brand repo to $OWNER/$REPO" git push origin master
You should be good to go now.
A good first step is to modify
content/metadata.yaml with the relevant information for your manuscript.
Merging upstream rootstock changes
This section will describe how to incorporate changes to rootstock that occurred since initializing your manuscript. You will want to do this if there are new enhancements or bugfixes that you want to incorporate. This process can be difficult, especially if conflicts have arisen, and is recommended only for advanced git users.
It is recommended to do rootstock upgrades via a pull request to help you view the proposed changes and to ensure the build uses the updated environment. First, checkout a new branch to use as the pull request head branch:
# This command names the branch using the current date, i.e. rootstock-2018-11-16 git checkout -b rootstock-`date '+%Y-%m-%d'`
Second, pull the new commits from rootstock, but do not automerge:
git pull --no-ff --no-commit rootstock master
If all goes well, there won't be any conflicts. However, if there are conflicts, follow the suggested commands to resolve them.
You can add the changes incrementally using
git add --patch.
This is helpful to see each upstream change.
You may notice changes that affect how items in
content are processed.
If so, you should edit and stage
content files as needed.
When there are no longer any unstaged changes, then do
master via a pull request, proceed to push the commit to GitHub and open a pull request.
Once the pull request is ready to merge, use GitHub's "Create a merge commit" option rather than "Squash and merge" or "Rebase and merge" to preserve the rootstock commit hashes.