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.
To enable automatic cherry-picking on a PR, add the label cherry-pick to it.
Without it, the responsible GitHub action is not going to be triggered.
To select the target branches you would like to cherry-pick your PR to, add labels of the following structure: cherry-pick-to-<targetBranch>.
For example: cherry-pick-to-cypher-25 to cherry-pick it to the branch cypher-25 or cherry-pick-to-5.x for the branch 5.x.
You may even add new labels for branches that do not have such a label yet.
The feature is triggered by either merging a PR with the cherry-pick label or by adding the cherry-pick label to an already closed and merged PR.
In the latter case, ensure that you first add the labels containing the target branches and then finally the cherry-pick label.
Otherwise the automation starts without any target branches.
The PRs created by this GitHub action will have their heading prefixed with [Cherry-pick][<targetBranch>].
So, for example, for 6.x as the target branch and some changes as the original PR heading, it results in [Cherry-pick][6.x] some changes as the heading for the cherry-picked PR.
In case an assignee was set for the original PR, the cherry-picked PRs will also receive the same assignee.
You must add reviewers manually after the cherry-picked PRs have been created.
The creation of cherry-picked PRs can take a few minutes. If you are an assignee of the original PR, you receive an email notification once the cherry-picked PRs have been created. The original PR is updated with a comment that contains links to the newly created cherry-picked PRs.
In case of a merge conflict while cherry-picking to a specific release branch, the branch will be skipped. Information on skipped branches is also included in the comment added to the original PR. In that case you will have to take care of cherry-picking manually and resolve the conflicts. This is not going to influence the other release branches as long as they do not have conflicts.
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.