_config.yml Documentation

1. Project Overview & Quickstart (openzipkin/_config.yml) Copy Chapter

_config.yml

Open-source repository openzipkin/_config.yml

Repository Details Copy Section

• Repository: openzipkin/_config.yml
• Primary Language: Code

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (openzipkin/openzipkin.github.io) Copy Chapter

File: README.md Copy Chapter

openzipkin.github.io

This repository contains the source code for the Zipkin documentation site
http://zipkin.io. It's the
organization page
for openzipkin, hosted using
GitHub pages and Jekyll.
This means that everything on the master branch is immediately and
automatically published.

It uses the static site generator Jekyll. Jekyll is
implemented in Ruby and requires Ruby
version >= 2.7.

Contributing Copy Chapter

Improvements to the documentation are more than welcome. This section tries to
get you up to speed on how to run the site locally and make changes. Just like
the documentation, this meta-documentation also welcomes all improvements. If
you can, you should use OSX or Linux; Jekyll is not very well supported on
Windows.

If you've done this kind of thing before Copy Section

You may wish to use rbenv to ensure your Ruby and Bundler versions are
consistent before proceeding.

1. Fork, branch, clone
2. bundle
3. jekyll serve
4. Make changes, commit, push
5. Open a pull-request

Preparing your environment Copy Section

1. Install Ruby

   The official documentation at
   https://www.ruby-lang.org/en/documentation/installation/ describes the
   procedure for all major operating systems.

2. System-level dependencies

   Nokogiri, one of the components used by Jekyll,
   requires some system-level libraries to be in place before installation of
   Jekyll can begin. Things should generally work out of the box, but keep in
   mind that if Jekyll installation fails referencing Nokogiri, then the
   Installing Nokogiri
   document most likely has what you need.

3. Clone the repository

   text Copy

   git clone https://github.com/openzipkin/openzipkin.github.io.git

4. Install Jekyll and friends

   GitHub quite considerately provides the exact list of packages that are used
   to generate the site on GitHub Pages, which means we can use the exact same
   packages when running the site locally. This minimizes differences between
   what you see locally, and what you'll see in production. Gemfile
   defines the packages to be installed using the list provided by GitHub (and
   Gemfile.lock makes sure we all have the same versions
   locally). To install these packages:

   text Copy

   cd openzipkin.github.io
    bundle

5. Run the site

   You're now all set! The following command starts Jekyll, and makes the site
   available at http://localhost:4000. It'll also pick
   up any changes you make locally, and regenerate the site, so you can review
   your changes live without having to restart Jekyll.

   text Copy

   bundle exec jekyll serve

Finding your way around the repository Copy Section

Next up is making some changes to the site. To do that, you'll need to have a
basic understanding of how the repository is structured.

Content for all the pages lives in the pages directory. This makes it
very clear where you need to look when making changes to the website text; it's
clearly separated from all the scaffolding around the actual content. The only
exception is the home page, index.md. It's in the root of the
repository for purely technical reasons (GitHub Pages can only serve the root
document from the root of the repository, and doesn't allow running any Jekyll
plugins).

The rest of the repository contains scaffolding; here's a list to give you a
basic idea of what's what:

• _data contains lists of things that are rendered into various
  parts of the page. For instance the list of tracers and instrumentation
  is defined here in a structured way.
• _includes contains HTML snippets that are shared by some or
  all pages.
• _layouts contains the basic HTML shared by all pages - and
  references snippets in _includes. At the time of writing, all pages use the
  page layout, and I don't foresee new layouts becoming actively used.
• _sass contains style-sheets implemented in Sass.
• public contains static content that's directly served to browsers as-is.
• .editorconfig contains
  EditorConfig configuration that makes sure
  editors supporting EditorConfig format files in this repository in the same
  way (think spaces vs tabs)
• CNAME tells GitHub pages that this site should be served at
  http://zipkin.io instead of
  http://openzipkin.zipkin.io. For details on
  how, see
  [https://help.github.com/articles/using-a-custom-domain-with-github-pages/](Using
  a custom domain with GitHub Pages)
• Gemfile and Gemfile.lock describe the Ruby
  packages used for building and serving this site; see the documentation of
  Bundler for more details.
• _config.yml contains configuration options used by Jekyll
  when generating the site.

Some finer points Copy Section

There are a few things to keep an eye out for while making changes to the site.

• For links to work correctly both locally, on forks, and in production, we
  need to include {{ site.github.url }} at the beginning of URLs. For
  example, a link to the Quickstart guide looks like this: {{ site.github.url }}/pages/quickstart. This is expanded by Jekyll to the correct value based
  on where it's running. More documentation is available
  here
• A link to each page appears in the side-bar. The links are ordered based on a
  custom value weight assigned to each page. By default each page has a
  weight of 100 - the default is defined in _config.yml. This can be
  overridden in each page, see index.md for an example. Pages
  with lower weight come first in the list. Pages with the same weight are
  sorted however Jekyll sees fit - probably alphabetically.
  * This is implemented by custom logic for in
  _includes/sidebar.html. As we add more
  content, we may want to add more structure to the side-bar, and we may
  need to re-think this approach. Worst case, we can manage the side-bar
  contents manually.

Creating a pull-request Copy Section

Once you've made your changes, you'll want to create a pull-request, so that the
changes can be merged into the master branch of
openzipkin/openzipkin.github.io, and so published for the betterment of all.
This section describes the steps for getting there, assuming you've followed the
instructions so far.

1. Fork this repository

   Go to
   openzipkin/openzipkin.github.io,
   and click the "Fork" button. Or just
   click here.

2. Tell git about your fork

   We're going to call your fork origin, and the original openzipkin
   repository upstream. The following commands tell git to make the
   appropriate changes:

   text Copy

   git remote rename origin upstream
    git remote add origin [email protected]:$USER/openzipkin.github.io
    git fetch upstream

3. Create a branch, commit and push your changes

   text Copy

   git checkout -b my-awesome-changes
    git commit -m 'Short, useful description of my changes'
    git push

4. Open a pull-request

   Open https://github.com/openzipkin/openzipkin.github.io. You should see a bar
   above the list of files that says you've recently pushed to your branch, with
   a green button on the right to open a pull request. Click it; add text to
   text fields and click buttons as appropriate. See
   https://help.github.com/articles/using-pull-requests/
   for detailed instructions.

Pulling changes Copy Section

When you come back to the project later, you'll want to make sure you have all
the recent changes downloaded before making any further changes. Note: the
following commands throw away any and all changes you have locally. If that's
not desired, refer to the documentation of your git client.

git checkout master
git fetch upstream
git reset --hard upstream/master
git push

You'll also want to make sure you have all the required Ruby packages, at
exactly the required versions:

bundle

You are now ready to start a new branch and add more awesome to the
documentation.

File: build-bin/README.md Copy Chapter

Test and Deploy scripts

This is a Jekyll project, which only includes the [test] command as files are served as-is with
GitHub Pages.

Unlike code-based projects, we test documentation-only commits: this is literally a website!

Build Overview Copy Chapter

build-bin holds portable scripts used in CI to test and deploy the project.

The scripts here are portable. They do not include any CI provider-specific logic or ENV variables.
This helps .travis.yml and test.yml (GitHub Actions) contain nearly the same contents, even if
certain OpenZipkin projects need slight adjustments here. Portability has proven necessary, as
OpenZipkin has had to transition CI providers many times due to feature and quota constraints.

These scripts serve a second purpose, which is to facilitate manual releases, which has also
happened many times due usually to service outages of CI providers. While tempting to use
CI-provider specific tools, doing so can easily create a dependency where no one knows how to
release anymore. Do not use provider-specific mechanisms to implement release flow. Instead,
automate triggering of the scripts here.

The only scripts that should be modified per project are in the base directory. Those in sub
directories, such as [docker], should not vary project to project except accident of version drift.
Intentional changes in sub directories should be relevant and tested on multiple projects to ensure
they can be blindly copy/pasted.

Conversely, the files in the base directory are project specific entry-points for test and deploy
actions and are entirely appropriate to vary per project. Here's an overview:

Test Copy Chapter

Test builds and runs any tests of the project, including integration tests. CI providers should be
configured to run tests on pull requests or pushes to the master branch, notably when the tag is
blank. Tests should not run on documentation-only commits. Tests must not depend on authenticated
resources, as running tests can leak credentials. Git checkouts should include the full history so
that license headers or other git analysis can take place.

• [configure_test] - Sets up build environment for tests.
• [test] - Builds and runs tests for this project.

Example GitHub Actions setup Copy Section

A simplest GitHub Actions test.yml runs tests after configuring them, but only on relevant event
conditions. The name test.yml and job test allows easy references to status badges and parity of
the scripts it uses.

The on: section obviates job creation and resource usage for irrelevant events. Notably, GitHub
Actions includes the ability to skip documentation-only jobs.

Combine [configure_test] and [test] into the same run: when configure_test primes file system
cache.

Here's a partial test.yml including only the aspects mentioned above.

on:
  push:
    tags: ''
    branches: master
    paths-ignore: '**/*.md'
  pull_request:
    branches: master
    paths-ignore: '**/*.md'

jobs:
  test:
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v2
        with:
          fetch-depth: 0  # full git history
      - name: Test
        run: build-bin/configure_test && build-bin/test

Example Travis setup Copy Section

.travis.yml is a monolithic configuration file broken into stages, of which the default is "test".
A simplest Travis test job configures tests in install and runs them as script, but only on
relevant event conditions.

The if: section obviates job creation and resource usage for irrelevant events. Travis does not
support file conditions. A before_install step to skip documentation-only commits will likely
complete in less than a minute (10 credit cost).

Here's a partial .travis.yml including only the aspects mentioned above.

git:
  depth: false  # full git history for license check, and doc-only skipping

jobs:
  include:
    - stage: test
      if: branch = master AND tag IS blank AND type IN (push, pull_request)
      name: Run unit and integration tests
      before_install: |
        if [ -n "${TRAVIS_COMMIT_RANGE}" ] && ! git diff --name-only "${TRAVIS_COMMIT_RANGE}" -- | grep -qv '\.md$'; then
          echo "Stopping job as changes only affect documentation (ex. README.md)"
          travis_terminate 0
        fi
      install: ./build-bin/configure_test
      script: ./build-bin/test

Deploy Copy Chapter

Deploy builds and pushes artifacts to a remote repository for master and release commits on it. CI
providers deploy pushes to master on when the tag is blank, but not on documentation-only commits.
Releases should deploy on version tags (ex /^[0-9]+\.[0-9]+\.[0-9]+/), without consideration of if
the commit is documentation only or not.

• [configure_deploy] - Sets up environment and logs in, assuming [configure_test] was not called.
• [deploy] - deploys the project, with arg0 being "master" or a release commit like "1.2.3"

Example GitHub Actions setup Copy Section

A simplest GitHub Actions deploy.yml deploys after logging in, but only on relevant event
conditions. The name deploy.yml and job deploy allows easy references to status badges and
parity of the scripts it uses.

The on: section obviates job creation and resource usage for irrelevant events. GitHub Actions
cannot implement "master, except documentation only-commits" in the same file. Hence, deployments of
master will happen even on README change.

Combine [configure_deploy] and [deploy] into the same run: when configure_deploy primes file
system cache.

Here's a partial deploy.yml including only the aspects mentioned above. Notice env variables are
explicitly defined and on.tags is a glob pattern.

on:
  push:
    tags: '[0-9]+.[0-9]+.[0-9]+**'  # Ex. 8.272.10 or 15.0.1_p9
    branches: master

jobs:
  deploy:
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v2
        with:
          fetch-depth: 1  # only needed to get the sha label
      - name: Deploy
        env:
          GH_USER: ${{ secrets.GH_USER }}
          GH_TOKEN: ${{ secrets.GH_TOKEN }}
        run: |  # GITHUB_REF will be refs/heads/master or refs/tags/N.M.L
          build-bin/configure_deploy &&
          build-bin/deploy $(echo ${GITHUB_REF} | cut -d/ -f 3)

Example Travis setup Copy Section

.travis.yml is a monolithic configuration file broken into stages. This means test and deploy
are in the same file. A simplest Travis deploy stage has two jobs: one for master pushes and
another for version tags. These jobs are controlled by event conditions.

The if: section obviates job creation and resource usage for irrelevant events. Travis does not
support file conditions. A before_install step to skip documentation-only commits will likely
complete in less than a minute (10 credit cost).

As billing is by the minute, it is most cost effective to combine test and deploy on master push.

Here's a partial .travis.yml including only the aspects mentioned above. Notice YAML anchors work
in Travis and tag =~ condition is a regular
expression.

git:
  depth: false  # full git history for license check, and doc-only skipping

_terminate_if_only_docs: &terminate_if_only_docs |
  if [ -n "${TRAVIS_COMMIT_RANGE}" ] && ! git diff --name-only "${TRAVIS_COMMIT_RANGE}" -- | grep -qv '\.md$'; then
    echo "Stopping job as changes only affect documentation (ex. README.md)"
    travis_terminate 0
  fi

jobs:
  include:
    - stage: test
      if: branch = master AND tag IS blank AND type IN (push, pull_request)
      before_install: *terminate_if_only_docs
      install: |
        if [ "${TRAVIS_SECURE_ENV_VARS}" = "true" ] && [ "${TRAVIS_PULL_REQUEST}" = "false" ]; then
          export SHOULD_DEPLOY=true
          ./build-bin/configure_deploy
        else
          export SHOULD_DEPLOY=false
          ./build-bin/configure_test
        fi
      script:
        - ./build-bin/test || travis_terminate 1
        - if [ "${SHOULD_DEPLOY}" != "true" ]; then travis_terminate 0; fi
        - travis_wait ./build-bin/deploy master
    - stage: deploy
      # Ex. 8.272.10 or 15.0.1_p9
      if: tag =~ /^[0-9]+\.[0-9]+\.[0-9]+/ AND type = push AND env(GH_TOKEN) IS present
      install: ./build-bin/configure_deploy
      script: ./build-bin/deploy ${TRAVIS_TAG}