## 1. Project Overview & Quickstart (openzipkin/Gemfile.lock)

# Gemfile.lock

Open-source repository openzipkin/Gemfile.lock

### Repository Details
- **Repository:** [openzipkin/Gemfile.lock](https://github.com/openzipkin/Gemfile.lock)
- **Primary Language:** Code

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

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

## File: README.md

# openzipkin.github.io

This repository contains the source code for the Zipkin documentation site
http://zipkin.io. It's the
[organization page](https://help.github.com/articles/user-organization-and-project-pages/)
for [`openzipkin`](https://github.com/openzipkin/), hosted using
[GitHub pages and Jekyll](https://help.github.com/articles/using-jekyll-as-a-static-site-generator-with-github-pages/).
This means that everything on the `master` branch is immediately and
automatically published.

It uses the static site generator [Jekyll](http://jekyllrb.com/). Jekyll is
implemented in [Ruby](https://www.ruby-lang.org/en/) and requires Ruby
version >= 2.7.

## Contributing

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
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

1. **Install Ruby**

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

   [Nokogiri](http://www.nokogiri.org/), 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](http://www.nokogiri.org/tutorials/installing_nokogiri.html)
   document most likely has what you need.
   
1. **Clone the repository**

        git clone https://github.com/openzipkin/openzipkin.github.io.git
        
1. **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`](Gemfile)
   defines the packages to be installed using the list provided by GitHub (and
   [`Gemfile.lock`](Gemfile.lock) makes sure we all have the same versions
   locally). To install these packages:
   
        cd openzipkin.github.io
        bundle
        
1. **Run the site**

   You're now all set! The following command starts Jekyll, and makes the site
   available at [http://localhost:4000](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.
   
        bundle exec jekyll serve


### Finding your way around the repository

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`](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`](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`](_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`](_includes) contains HTML snippets that are shared by some or
   all pages.
 * [`_layouts`](_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`](_sass) contains style-sheets implemented in [`Sass`](http://sass-lang.com/).
 * [`public`](public) contains static content that's directly served to browsers as-is.
 * [`.editorconfig`](.editorconfig) contains
   [EditorConfig](http://editorconfig.org/) configuration that makes sure
   editors supporting EditorConfig format files in this repository in the same
   way (think spaces vs tabs)
 * [`CNAME`](CNAME) tells GitHub pages that this site should be served at
   [http://zipkin.io](http://zipkin.io) instead of
   [http://openzipkin.zipkin.io](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`](Gemfile) and [`Gemfile.lock`](Gemfile.lock) describe the Ruby
   packages used for building and serving this site; see the documentation of
   [Bundler](http://bundler.io/) for more details.
 * [`_config.yml`](_config.yml) contains configuration options used by Jekyll
   when generating the site.

### Some finer points

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](https://jekyllrb.com/docs/github-pages/)
 * 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`](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`](_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

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](https://github.com/openzipkin/openzipkin.github.io),
    and click the "Fork" button. Or just
    [click here](https://github.com/openzipkin/openzipkin.github.io/fork).
    
1. **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:
   
        git remote rename origin upstream
        git remote add origin git@github.com:$USER/openzipkin.github.io
        git fetch upstream
        
1. **Create a branch, commit and push your changes**

        git checkout -b my-awesome-changes
        git commit -m 'Short, useful description of my changes'
        git push
        
1. **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/](https://help.github.com/articles/using-pull-requests/)
   for detailed instructions.
   
### Pulling changes
   
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

# 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!

[//]: # (Below here should be standard for all projects)

## Build Overview
`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

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

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.
```yaml
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
`.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.
```yaml
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

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

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](https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet).
```yaml
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
`.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](https://github.com/travis-ci/travis-conditions) is a regular
expression.
```yaml
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}
```