Neo4j Cypher Manual

Building locally

Prereqs

• Node.js

• npm

Installation

To install the required packages:

npm i

Generating HTML output

To convert asciidoc source to HTML:

npm run build

Viewing HTML output

To view the built site, launch a local server:

1. npm start

2. In a browser tab, go to localhost:8000

Live preview

When you run npm start, the project is monitored for updates to asciidoc files.

If a change to an asciidoc file is detected, the site is automatically rebuilt.

Errors

Check for xref errors and other warnings.

./node_modules/@antora/cli/bin/antora preview.yml 2>&1 | tee build.log

Raising PRs

Branch management

The docs-cypher repo (and all CoreDB docs repos) will contain the following branches:

• 4.4 - Long term support

• 5.x - this is the currently published version, and therefore is the branch that we publish all v5 docs from.

  • PRs merged into this branch will be published live immediately.

• dev - this is always the next release - this branch will be published on the staging server, as a preview, but we will never publish from this branch publicly.

  • Next means the “next version of documentation”, and may not mirror other Neo4j engineering repos. Within Github we’ll update the branch descriptions with what the current and next versions are.

• Work on older branches (3.5, 4.0, 4.1, 4.2, 4.3) should be seen as “only when absolutely necessary”.

Raising PRs, and the publishing process

Here is the workflow for creating PRs in the repo, and our publication process:

• For any work on the current version, all work should be raised & merged against the dev branch, and cherry-picked back to 5.x branch. There are a few edge cases where we might want to work only on the current branch, for example adding a warning that is not needed in the next version - this is ok!

• For content relating to the next release, raise PRs against the dev branch and use labels to mark the specific version it is targeting.

• For work on next+n docs (i.e a version beyond next), we have 2 options:

  • Open a draft PR against dev, with a label for the specific version it is targeting - this can be shared & reviewed in draft mode, but will not be mergeable until it is pointed at the next release.

  • Create a feature branch from dev, to be merged into dev when appropriate.

• When a new version is ready to published, the 5.x branch will get a git tag, named with the exact version (for example, 5.1.0), signifying that this point-in-time marks the completion of the work for that minor release.

• Updates merged into the dev branch for the next release are cherry-picked into the 5.x branch.