diff --git a/README.adoc b/README.adoc index 71281a24f..70c2df006 100644 --- a/README.adoc +++ b/README.adoc @@ -1,5 +1,14 @@ = Neo4j Cypher Manual +This page covers the following topics: + +* xref:README.adoc#building-locally[] +* xref:README.adoc#raising-prs[] +* xref:README.adoc#documenting-changes[] +* xref:README.adoc#cypher-gql[] + + +[[building-locally]] == Building locally === Prereqs @@ -39,7 +48,7 @@ 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]] == Raising PRs @@ -68,3 +77,43 @@ There are a few edge cases where we might want to work only on the current branc ** 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]] +== Documenting changes to Cypher + +New, updated, deprecated, and removed features must be recorded on the xref:modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc[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-gql]] +== 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 xref:modules/ROOT/pages/appendix/gql-conformance/supported-mandatory.adoc[Supported mandatory GQL features]. +* If the feature is part of GQL's optional features, it should be recorded on the page xref:modules/ROOT/pages/appendix/gql-conformance/supported-optional.adoc[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 xref:modules/ROOT/pages/appendix/gql-conformance/analogous-cypher.adoc[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 xref:modules/ROOT/pages/appendix/gql-conformance/additional-cypher.adoc[Additional Cypher features].