Adds basic Spring Data Envers specific documentation. #279
Conversation
|
Paging @Buzzardo |
src/main/asciidoc/envers.adoc
Outdated
| == Getting Started | ||
|
|
||
| As a starting point for using Spring Data Envers you need a project with Spring Data JPA. | ||
| The easiest way to create that is using the Spring Initializr either on start.spring.io or via its integration in your favorite IDE. |
src/main/asciidoc/envers.adoc
Outdated
|
|
||
| </dependencies> | ||
| ---- | ||
| This will also bring hibernate-envers into the project as a transient dependency. |
There was a problem hiding this comment.
Nit: Code fences for hibernate-envers
src/main/asciidoc/envers.adoc
Outdated
| ---- | ||
| public interface PersonRepository | ||
| extends CrudRepository<Person, Long>, | ||
| RevisionRepository<Person, Long, Long> {} |
There was a problem hiding this comment.
It would be nice to add callouts and explain Person, Long, Long. It's not obvious why there's Long, Long.
src/main/asciidoc/envers.adoc
Outdated
| public class EnversDemoConfiguration {} | ||
| ---- | ||
|
|
||
| The entity for that repository should be an entity with Envers auditing enabled, i.e. it has an `@Audited` annotation. |
There was a problem hiding this comment.
Should or is this a hard requirement?
src/main/asciidoc/envers.adoc
Outdated
| [source,java] | ||
| ---- | ||
| @ExtendWith(SpringExtension.class) | ||
| @SpringBootTest |
There was a problem hiding this comment.
Can we rewrite the test to not require Spring Boot?
There was a problem hiding this comment.
Wouldn't that mean we have to reference an application context configuration which then should also be included in the example? Or are you aiming for something else?
src/main/asciidoc/envers.adoc
Outdated
|
|
||
| Revisions<Long, Person> revisions = repository.findRevisions(updated.id); | ||
|
|
||
| assertThat(revisions) // |
There was a problem hiding this comment.
The // are rather distracting. Also, let's rewrite the test to a more simple form. extracting(…) and tuple aren't quite what we should expect from our audience as pre-requisite.
There was a problem hiding this comment.
Fully agree on the //
But I consider AssertJ the de facto standard of assertions and extracting + tuple essential and easy to understand features. Rewriting this would make it harder to understand AND enforces bad practices. I'm somewhat reluctant to do that.
There was a problem hiding this comment.
My motivation is that our example should be focusing on our bits/Envers bits as much as possible. The tests should just decorate the example and require as little knowledge as possible as the cognitive load to understand how to use Revisions is quite high for someone that wants to learn the topic. We should reduce the impact of our decoration on the learning steps.
| john.setName("John"); | ||
|
|
||
| //create | ||
| Person saved = tx.execute(__ -> repository.save(john)); |
There was a problem hiding this comment.
Let's replace __ with transactionStatus for a more expressive example.
There was a problem hiding this comment.
Again I don't find that more expressive but unnecessary verbose.
There was a problem hiding this comment.
While it's more verbose it avoids confusion with Kotlin or Scala-like implicit lambda parameters and it's not implying that any potentially newer and lesser-known feature is used. That being said, trying to remove obstacles.
Closes #61 See spring-projects/spring-data-examples#603 Original pull request: #279.
Closes #61 See spring-projects/spring-data-examples#603 Original pull request: #279.
Closes #61 See spring-projects/spring-data-examples#603 Original pull request: #279.
|
That's merged, polished, and backported now. |
Closes #61
See spring-projects/spring-data-examples#603