Skip to content

Rewrite README about branches #1711

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 27, 2020
Merged

Rewrite README about branches #1711

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 18 additions & 13 deletions README.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -220,19 +220,24 @@ You can add a new repository under the `repos` section, if it
doesn't already exist, and you can add a new "book" under the
`contents` section.

The `repos.$NAME.branches[]` key lists all of the branches which
should be built -- all of these branches will be available on the
website -- while `repos.$NAME.current` lists the branch which
should be used as the default version on the site.

NOTE: The `branches` and `current` settings can be overridden in
the config for each book. For instance, the "Community Clients"
docs are built only from the `master` branch.

When you release a new version of your code, you need to add
a new `branch` to the config and to update the `current` branch
for your project. Commit the change to https://github.com/elastic/docs/blob/master/conf.yaml[`conf.yaml`] and push
to the remote `docs` repo.
Each book contains a list of `branches` and we build a separate copy of each
book for each of those `branches`. There is also a `current` branch which gets
special treatment. When we fork a branch like like 7.x or 7.9 we typically add
it to the list of `branches` so we immediately start building docs for it while
we're actively developing against it. When we release a new minor or major
version we update the `current` branch to point to that branch.

NOTE: At this point changing `current` requires a full "rebuild" which we do
by logging into the docs
https://elasticsearch-ci.elastic.co/view/Docs/job/elastic+docs+master+build/[build]
clicking the "Build with Parameters" link, checking the "rebuild" option, and
then starting the build.

Each book may optionally contain a list of `live` branches. If the list is
specified only branches that are in it are considered "living" and books that
are not in the list will get a message at the top of each page saying that we
don't plan to release any more bug fixes or actively maintain the docs for that
branch.

[[asciidoc-guide]]
= Asciidoc Guide
Expand Down