/draco.git
HEAD branch: master
Remote branch:
master tracked
Local branch configured for 'git pull':
master merges with remote master
Local ref configured for 'git push':
master pushes to master (up to date)
$ git remote show upstream
* remote upstream
Fetch URL: git@github.com:google/draco.git
Push URL: git@github.com:google/draco.git
HEAD branch: master
Remote branch:
master tracked
Local ref configured for 'git push':
master pushes to master (up to date)
~~~~~
[**See this page**][1] for a longer discussion of managing remotes and general
GitHub workflow.
**Important: The following commands should be issued from the `docs/`
directory.**
### Set Local Ruby Version (rbenv)
_**In the `docs/` directory**_ of your local clone, do:
~~~~~
rbenv local 2.3.0
~~~~~
Regardless of any other Rubies installed on your system, the project environment
will now use v2.3.0 and gems appropriate for it.
### Install Gem Dependencies with Bundler
In the `docs/` directory of your local clone, run
~~~~~
bundle install
~~~~~
Bundler will set dependencies and install needed gems as listed in
`Gemfile.lock`.
_**Note** that you may need Ruby development headers installed on your system
for some gems to compile successfully._
### Build and Preview Locally with Jekyll
~~~~~
bundle exec jekyll serve
~~~~~
This will build the documentation tree and launch a local webserver at
`http://127.0.0.1:4000/docs/` (by default). Jekyll will also watch the
the filesystem for changes and rebuild the document as needed.
## **Markdown & Formatting Conventions**
The spec document is composed mostly of syntax tables, styled with CSS. Mark
them up as follows:
* Use the [fenced code block][fenced] kramdown syntax: A line beginning with
three or more tildes (`~`) starts the code block, another such line ends it.
* Use kramdown's [inline attribute syntax][inline] to apply the CSS class
`draco-syntax` to your code block by placing `{:.draco-syntax }` on the line
immediately after the code-block closing delimiter.
* Some syntax elements as annotated with their type and size in a right-hand
column. In your text editor, position these annotations at column **86**.
**Example:**
~~~~~
DecodeHeader() {
draco_string UI8[5]
major_version UI8
minor_version UI8
encoder_type UI8
encoder_method UI8
flags
}
~~~~~
{:.draco-syntax}
... **will render as:**
~~~~~
DecodeHeader() {
draco_string UI8[5]
major_version UI8
minor_version UI8
encoder_type UI8
encoder_method UI8
flags
}
~~~~~
{:.draco-syntax}
## General GitHub Workflow
Always do your work in a local branch.
~~~~~
git co -b my-branch-name
## work ##
git add
git ci -m "Reasonably clear commit message"
~~~~~
Push your branch to `origin` (your GitHub fork):
~~~~~
git push origin my-branch-name
~~~~~
Next, visit the `upstream` [homepage]. If you are logged-in, GitHub will be
aware of your recently pushed branch, and offer an in-page widget for submitting
a pull request for the project maintainers to consider.
Once your pull request is merged into upstream's master branch, you may
synchronize your clone (and remote `origin`) as follows:
~~~~~
git co master
git fetch upstream
git merge upstream/master
git push origin
~~~~~
Your old working branch is no longer needed, so do some housekeeping:
~~~~~
git br -d my-branch-name
~~~~~
[Markdown]: https://daringfireball.net/projects/markdown/
[kramdown]: https://kramdown.gettalong.org/
[Jekyll]: https://jekyllrb.com/
[rbenv]: https://github.com/rbenv/rbenv
[bundler]: http://bundler.io/
[install rbenv]: https://github.com/rbenv/rbenv#installation
[homepage]: https://github.com/google/draco
[using SSH]: https://help.github.com/articles/connecting-to-github-with-ssh/
[1]: https://2buntu.com/articles/1459/keeping-your-forked-repo-synced-with-the-upstream-source/
[fenced]: https://kramdown.gettalong.org/syntax.html#fenced-code-blocks
[inline]: https://kramdown.gettalong.org/syntax.html#block-ials