From 549a17c63b56a403a42bc944ab702306b2a43119 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Tue, 5 Nov 2024 16:25:08 +0100 Subject: [PATCH 1/7] add instructions for changes in language and gql --- README.adoc | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/README.adoc b/README.adoc index 71281a24f..eafa42a43 100644 --- a/README.adoc +++ b/README.adoc @@ -1,5 +1,14 @@ = Neo4j Cypher Manual +This page covers the following topics: + +* xref:README.adoc#build-locally[] +* xref:README.adoc#raise-prs[] +* xref:README.adoc#documenting-changes[] +* xref:README.adoc#cypher-gql[] + + +[[build-locally]] == Building locally === Prereqs @@ -68,3 +77,38 @@ 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:deprecations-additions-removals-compatibility.adoc[] 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 removed 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[] +* 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[] +* if the feature adds functionality for which there exists an analogous GQL equivalent, it should be recorded on the page xref:modules/ROOT/pages/appendix/gql-conformance/analogous-cypher.adoc[] +* 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[] From 65e661fefac85fabf1c41a0667e95960564fcbdc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Tue, 5 Nov 2024 16:27:20 +0100 Subject: [PATCH 2/7] add anchor --- README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index eafa42a43..13d6b8632 100644 --- a/README.adoc +++ b/README.adoc @@ -48,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. - +[[raise-prs]] == Raising PRs From 331fd670cf9327318b8c05b939c19557d124b343 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Tue, 5 Nov 2024 16:30:53 +0100 Subject: [PATCH 3/7] fix --- README.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.adoc b/README.adoc index 13d6b8632..34ce0d181 100644 --- a/README.adoc +++ b/README.adoc @@ -84,6 +84,7 @@ There are a few edge cases where we might want to work only on the current branc New, updated, deprecated, and removed features must be recorded on the xref:deprecations-additions-removals-compatibility.adoc[] 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] @@ -94,8 +95,8 @@ New and deprecated features should also be marked with a label: * 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[] +`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. From 25199e2a1fc5828a9f70fd70775760d9e7eec92e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Tue, 5 Nov 2024 16:38:39 +0100 Subject: [PATCH 4/7] a few full stops --- README.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.adoc b/README.adoc index 34ce0d181..3816dec47 100644 --- a/README.adoc +++ b/README.adoc @@ -109,7 +109,7 @@ Removed features should be removed 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 xref:modules/ROOT/pages/appendix/gql-conformance/supported-mandatory.adoc[] -* 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[] -* if the feature adds functionality for which there exists an analogous GQL equivalent, it should be recorded on the page xref:modules/ROOT/pages/appendix/gql-conformance/analogous-cypher.adoc[] -* 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[] +* 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[]. +* 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[]. +* if the feature adds functionality for which there exists an analogous GQL equivalent, it should be recorded on the page xref:modules/ROOT/pages/appendix/gql-conformance/analogous-cypher.adoc[]. +* 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[]. From aaa92c04a81934eb3830d12d7e3e767c413eaf50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Thu, 7 Nov 2024 08:54:29 +0100 Subject: [PATCH 5/7] update --- README.adoc | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/README.adoc b/README.adoc index 3816dec47..34fc305c1 100644 --- a/README.adoc +++ b/README.adoc @@ -2,13 +2,13 @@ This page covers the following topics: -* xref:README.adoc#build-locally[] -* xref:README.adoc#raise-prs[] +* xref:README.adoc#building-locally[] +* xref:README.adoc#raising-prs[] * xref:README.adoc#documenting-changes[] * xref:README.adoc#cypher-gql[] -[[build-locally]] +[[building-locally]] == Building locally === Prereqs @@ -48,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. -[[raise-prs]] +[[raising-prs]] == Raising PRs @@ -87,11 +87,16 @@ 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 +== Header +.... +.... [role=label--deprecated] -\== Header +== Header +.... * If the impacted feature is documented within a table (such as a return column in a `SHOW` command), use the following: @@ -102,7 +107,7 @@ 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 removed from the Cypher Manual. +Removed features should be deleted from the Cypher Manual. [[cypher-gql]] == Cypher and GQL @@ -111,5 +116,5 @@ When documenting a new Cypher feature, its relationship with GQL must be conside * 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[]. * 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[]. -* if the feature adds functionality for which there exists an analogous GQL equivalent, it should be recorded on the page xref:modules/ROOT/pages/appendix/gql-conformance/analogous-cypher.adoc[]. +* if the feature adds functionality for which there exists an analogous GQL feature, it should be recorded on the page xref:modules/ROOT/pages/appendix/gql-conformance/analogous-cypher.adoc[]. * 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[]. From 86703f1da110995a38a0aa5983edfbaabc9c6985 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Thu, 7 Nov 2024 09:03:30 +0100 Subject: [PATCH 6/7] fix links --- README.adoc | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/README.adoc b/README.adoc index 34fc305c1..acdcc279a 100644 --- a/README.adoc +++ b/README.adoc @@ -81,13 +81,12 @@ There are a few edge cases where we might want to work only on the current branc [[documenting-changes]] == Documenting changes to Cypher -New, updated, deprecated, and removed features must be recorded on the xref:deprecations-additions-removals-compatibility.adoc[] page. +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 @@ -105,7 +104,7 @@ New and deprecated features should also be marked with a label: 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 ..." +For example: "As of Neo4j 5.x, `featureX` supports ..." Removed features should be deleted from the Cypher Manual. @@ -114,7 +113,7 @@ 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 xref:modules/ROOT/pages/appendix/gql-conformance/supported-mandatory.adoc[]. -* 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[]. -* if the feature adds functionality for which there exists an analogous GQL feature, it should be recorded on the page xref:modules/ROOT/pages/appendix/gql-conformance/analogous-cypher.adoc[]. -* 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[]. +* 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]. From d196b070a4617f9bb84f6de74ada361e574cbe17 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Thu, 7 Nov 2024 09:05:20 +0100 Subject: [PATCH 7/7] fix --- README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index acdcc279a..70c2df006 100644 --- a/README.adoc +++ b/README.adoc @@ -81,7 +81,7 @@ There are a few edge cases where we might want to work only on the current branc [[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, 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: