How to handle doc changes for not yet released features

[watson]

Problem

As it's currently configured, all documentation changes that are merged into the master branch is automatically deployed to this URL: www.elastic.co/guide/en/apm/agent/nodejs

Say we're merging in a PR that contains a new feature. The PR should also contain the documentation for said feature. As soon as it's merged into master, the documentation will go live, but if we don't publish a new version of the module containing that new feature right away, the documentation will be out of sync with the module people get when running npm install elastic-apm-node.

It would be convenient if we had a way to deal with that.

Background

Today the Node.js agent have only one set of documentation, but it's possible to have different versions of the documentation for different releases and even one for stuff that's not yet published. This is all controlled in the conf.yml file in the docs repo:

https://github.com/elastic/docs/blob/320c4229b14a9e82e1d5a231590d7787af033fce/conf.yaml#L762-L772

The configuration lists an array of branches, each of which should be a branch in the agent repository and each of which will result in a separate version of the docs. There's also a special key called current which points to the default documentation that should be shown to users unless they choose otherwise.

If there's more than one branch, it will result in a dropdown on the documentation pages from which you can choose the version of the documentation you want to view:

Solution 1

Change the one branch listed in the branches array to something else than master, e.g. latest, and then have that be a branch that we merge master into after we publish a new version of the agent to npm (i.e. no commits directly to the latest branch).

Solution 2

Have one branch per major version of the agent and list each of those (+ master) in the branches array in conf.yml. This is similar to how the Python agent handles it and also how Node.js core manages releases.

If we choose this solution, we need to find a good/easy way to get the commits from master into the release branch and how to do the actual release.

The easiest way (which doesn't allow us to make patch or minor releases to an old major version though), would be to still to do the release from the master branch, but then merge it into the latest release branch right after and not allow any commits directly to the release branch. Here release branches of older major versions would never receive new commits after a new major was released.

Suggestions welcome :)

Solution x

Please come with other solutions if I'm there's something I overlooked.

[watson]

cc @elastic/apm

[ruflin]

What I would expect:

• Everything merged into master will show up in the master docs. The "master" branch is not the one that is installed through npm install elastic-apm-node. More something like npm install --branch=master elastic-apm-node (or what option exists there in npm ...).
• npm install elastic-apm-node installs the most recent release tag. I assume there is an option in npm that a version can be specified.

The above I think would resemble what the rest of the stack does.

[watson]

@ruflin npm doesn't install directly from github by default (it's possible, but normally not recommended). Instead packages are downloaded from the central npm registry as tar-balls. They are uploaded by the developer once the developer cut a release. So a release is basically the developer making a new commit which bumps the version number and then uploads a tar-ball to the the registry containing whatever files was in his local directory at the time the tar-ball was created.

As a developer I can make this release commit in any branch. Most projects do this in the master branch. But if a project needs to support making patch releases for older releases, they tend to have branches for each major release in which the developer will make and push these release commits that bumps the version. But this is usually just there to benefit the developer. The user of the module will still just install it from the npm registry as any other version without knowing anything about, nor specifying a git branch, commit, or tag.

(In case you're interested, to install from master - or any other git ref for that matter - you'd write npm install <github-user>/<repo>[#<ref>])

TL;DR:

My point is that we're free to choose a branch strategy without considering how people are installing the module. Instead I think we should optimize of how easy it is to us manage and work with every day, as long as it lives up to our minimum requirements: E.g. can we display the docs how we want + does it allow us to make the releases that we need.

[Qard]

A single branch rather than a branch per major is probably enough for now. I wouldn't expect us to need to do a lot of backporting. We can always reevaluate that in the future.

[watson]

We since decided to have branches for each major version. That solves this issue, so I'll close for now