Skip to content

Releases: neo4j/docs-cypher

2025.04.0: Update styleguide with cypherfmt rules and recommend its usage (#1289)

04 Jun 07:02
Compare
Choose a tag to compare
## Description
Hey, docs team! For the past few months, as a master's thesis project,
@simonthuresson and I have been working on a formatter for Cypher. In
short, the formatter formats a Cypher query so that it follows the
styleguide recommendations. During development, we found that the
styleguide is quite far from comprehensive, and also some of the cypher
snippets in the docs disagree with it as well. Filling out the missing
pieces and addressing any ambiguity became a fairly large part of our
project, and we wrote extensively about how we did so in our thesis,
which you can find here:

- [An Evaluation of Approaches to Code
Formatting](https://lup.lub.lu.se/luur/download?func=downloadFile&recordOId=9188816&fileOId=9188817)

In short, we did a survey on styling preferences, and talked to Cypher
users to try and figure out what the most preferred way of writing
Cypher was. We then took those learnings and implemented it in our
formatter so that it could automatically enforce the rules.

This PR is a draft of how we think the styleguide should be updated in
accordance with the new rules. I did not put a lot of time into the
wording and structure of the recommendations, as I would prefer to leave
that to the professionals (you), but I provided some examples which
hopefully illustrate the ideas well. If you want more detailed context
on the rules, refer to the thesis (chapter 4 specifically). I also
included a recommendation at the start of the style guide that users
should use our formatter, as manual formatting is generally not a great
idea.

#### Note
I included a link to the language support npm package that I claim
provides a command-line tool. This is not actually live yet, but will be
soon: https://github.com/neo4j/cypher-language-support/pull/518

## Try it out
If you want to get a better feel for how the formatter works and how it
applies the rules, you can try it out in:
- Query in the Aura console (the ... menu -> format query)
- [The Cypher Language Support CodeMirror
playground](https://neo4j.github.io/cypher-language-support/)
- [VS
Code](https://marketplace.visualstudio.com/items?itemName=neo4j-extensions.neo4j-for-vscode)

I would also recommend running any Cypher queries you add to the docs
through the formatter first, to ensure that the styling is always
consistent across all documentation.

## Note
This is my last day at Neo4j, so I probably will not be able to respond
to any comments on this PR. If you have questions, direct them at the
language support team (#team-cypher-language-support), they have
reviewed every line of code in the formatter, and are well aware of how
it works. Feel free to completely change the wording I have used, this
is just a first draft that I wanted to get in before leaving.

---------

Co-authored-by: Jens Pryce-Åklundh <112686610+JPryce-Aklundh@users.noreply.github.com>

2025.03.0

30 Apr 14:22
Compare
Choose a tag to compare
fix variable names (#1261)

2025.02.0: fix SHORTEST note (#1217)

28 Mar 08:23
Compare
Choose a tag to compare
Co-authored-by: Neil Dewhurst <ndewhurst@gmail.com>

2025.01.0

28 Feb 07:35
Compare
Choose a tag to compare

What's Changed

Full Changelog: 5.26.0...2025.01.0

5.26.0

04 Feb 08:34
Compare
Choose a tag to compare

What's Changed

Read more

5.24.0

31 Oct 09:08
Compare
Choose a tag to compare

What's Changed

Full Changelog: 5.23.0...5.24.0

5.23.0

26 Sep 06:57
Compare
Choose a tag to compare
adding property rules to 5.21 additions (#1046)

Co-authored-by: Jens Pryce-Åklundh <112686610+JPryce-Aklundh@users.noreply.github.com>

5.20.0

28 Jun 10:15
Compare
Choose a tag to compare
Adding stable ids to all changes in 5.0 to be linkable (#988)

This will be used by Aura migration readiness report

5.19.0

27 May 07:34
Compare
Choose a tag to compare

What's Changed

New Contributors

Full Changelog: 5.17.0...5.19.0

5.17.0

13 Mar 15:19
Compare
Choose a tag to compare

What's Changed

Full Changelog: 5.16.0...5.17.0