This page covers the following topics:
To view the built site, launch a local server:
-
npm start -
In a browser tab, go to
localhost:8000
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”.
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
devbranch, and cherry-picked back to5.xbranch. 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 intodevwhen appropriate.
-
-
When a new version is ready to published, the
5.xbranch 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
devbranch for the next release are cherry-picked into the5.xbranch.
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
SHOWcommand), 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.
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.