Neo4j Cypher Manual

This page covers the following topics:

• Building locally

• Raising PRs

• Documenting changes to Cypher

• Cypher and GQL

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.

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.

Documenting changes to Cypher

New, updated, deprecated, and removed features must be recorded on the Deprecations, additions, and compatibility page.

New and deprecated features should also be marked with a label:

• If the impacted feature has its own header in the Cypher Manual, use the following:

[role=label--new-5.x]
== Header

[role=label--deprecated]
== Header

• If the impacted feature is documented within a table (such as a return column in a SHOW command), use the following:

featureX label:new[Introduced in 5.x]
featureY label:deprecated[]

Labels can be difficult to apply to updated features. In these cases, it is often preferable to note the change in a sentence. For example: "As of Neo4j 5.x, featureX supports …​"

Removed features should be deleted from the Cypher Manual.

Cypher and GQL

When documenting a new Cypher feature, its relationship with GQL must be considered:

• If the feature is part of GQL’s mandatory features, it should be recorded on the page Supported mandatory GQL features.

• If the feature is part of GQL’s optional features, it should be recorded on the page Supported optional GQL features.

• if the feature adds functionality for which there exists an analogous, optional GQL feature, it should be recorded on the page Optional GQL features and analogous Cypher.

• If the feature adds functionality for which there exists no GQL equivalent, it should be recorded on the page Additional Cypher features.