hk2166 opened a new pull request, #16776:
URL: https://github.com/apache/grails-core/pull/16776
## Description
A domain class that extends an abstract base class from `src/main/groovy`
only tracks changes to the inherited properties when the base class is
annotated with `@DirtyCheck`. GORM 6.1 explained this in an upgrade note
(673e31924e), but that note is no longer in the docs, and no current guide
mentions it. This adds a **Dirty Checking and Abstract Base Classes** section,
with the example from that note, to:
- the Hibernate 5 guide: `persistenceBasics/modificationChecking.adoc`
- the MongoDB guide: `objectMapping/dirtyChecking.adoc`
As agreed in #14185, this targets 7.0.x so that the merge up carries it to
every line.
### What the new sections say, and where it comes from
- **Inherited properties are only tracked with `@DirtyCheck`.**
`DirtyCheckingTransformer` only instruments the setters declared in the class
it transforms. A parent that is a domain class or carries `@DirtyCheck` is
transformed itself; any other parent is not. `DirtyCheckTransformationSpec`
("Test dirty check with abstract inheritance") covers the annotated pattern.
- **Hibernate 5: a change to an inherited property alone is not saved.**
`GrailsEntityDirtinessStrategy` treats a managed instance as dirty only when
`hasChanged()` says so, and checks each attribute with
`hasChanged(propertyName)`. The wording says "alone" because, if a tracked
property changes in the same flush, Hibernate may write the column anyway.
- **MongoDB: an untracked change is not saved.** `PersistentEntityCodec`
builds the update from `listDirtyPropertyNames()` only.
- **A base class that is itself a domain class needs no annotation**,
because the transformer accepts a domain-class parent.
### Hibernate 7 guide
`grails-data-hibernate7/docs/.../persistenceBasics/modificationChecking.adoc`
exists only on 8.x, so the merge up cannot reach it. Once this is merged up,
I'll open a small follow-up PR on 8.0.x that adds the same section there.
### Verification
- `./gradlew :grails-data-hibernate5-docs:asciidoctor
:grails-data-mongodb-docs:asciidoctor` builds successfully. AsciiDoctor only
prints `INFO: possible invalid reference` lines for existing pages
(`dynamicAttributes`, `gettingStarted`, `ormdsl`, `constraints`). The new
sections contain no cross-references.
- In both generated manuals, the new section renders in the per-section page
and in the single-page `index.html`, with its heading, the explanation, the
`@DirtyCheck` example and both notes.
Fixes #14185
Generative AI tooling (Claude Code) was used to research the behaviour in
the code and prepare this change.
## Contributor Checklist
Please review the following checklist before submitting your pull request.
Pull requests that do not meet these requirements may be closed without review.
### Issue and Scope
- [x] This PR is linked to an existing issue that has been **acknowledged or
approved** by the project team. If no approved issue exists, please give
background on why this change is necessary. Tickets are preferred for release
change log history.
- [ ] This PR addresses the **complete scope** of the linked issue. Partial
implementations or unfinished work should not be submitted for review. *(Covers
the Hibernate 5 and MongoDB guides. The Hibernate 7 guide is 8.x-only and
follows in a separate PR on 8.0.x, see above.)*
- [x] This PR contains a **single, focused change**. Unrelated changes
should be submitted as separate pull requests.
- [x] This PR targets the **correct branch** for the type of change:
- **Patch release branches** (e.g., `7.0.x`): Bug fixes only. No new
features or API changes.
- **Minor release branches** (e.g., `7.1.x`): New features are welcome,
but breaking existing APIs must be avoided.
- **Major release branches** (e.g., `8.0.x`): Reserved for major
changes. Breaking API changes are permitted.
### Code Quality
- [ ] I have **added or updated tests** that cover the changes introduced in
this PR. All code contributions are expected to include appropriate test
coverage. *(Documentation-only change; verified by building both guides, see
above.)*
- [ ] I have verified that all existing tests pass by running `./gradlew
build --rerun-tasks`. *(Not run; documentation-only change.)*
- [ ] My code follows the project's **code style** guidelines. I have run
`./gradlew codeStyle` and resolved any violations. See [Code
Style](../CONTRIBUTING.md#code-style) for details. *(Not applicable to `.adoc`
files.)*
- [x] This PR does **not** include mass reformatting, style-only changes, or
large-scale refactoring unless it was **explicitly approved** in the linked
issue. Unsolicited reformatting will not be accepted.
- [x] If generative AI tooling was used in preparing this contribution, a
quality model was used to ensure contributions are **consistent with the
project's quality standards**.
### Licensing and Attribution
- [x] All contributed code is provided under the [Apache License
2.0](https://www.apache.org/licenses/LICENSE-2.0), and new source files include
the appropriate **Apache license header**.
- [ ] I have the necessary rights to submit this contribution and confirm it
is my own original work (see [Legal
Notice](../CONTRIBUTING.md#i-want-to-contribute)).
- [x] If generative AI tooling was used in preparing this contribution, I
have followed the [Apache Software Foundation's policy on generative
tooling](https://www.apache.org/legal/generative-tooling.html) and have
properly attributed its use.
### Documentation
- [x] If this PR introduces user-facing changes, I have included or updated
the relevant documentation.
- [x] If this PR adds a new feature, I have updated the **What's New**
section of the Grails Guide.
- [x] If this PR introduces breaking changes or changes that require user
action during an upgrade, I have updated the **Upgrade Notes** for the
corresponding version in the Grails Guide.
- [x] The PR description clearly explains **what** was changed and **why**.
---
> **First-time contributors:** Please read our [Contributing
Guide](../CONTRIBUTING.md) before submitting.
> Pull requests that appear to be auto-generated, incomplete, or unrelated
to an approved issue may be
> closed to help maintainers focus on reviewed and planned work. We
appreciate your understanding.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
