Merge remote-tracking branch 'origin/8.0.x' into 8.1.x

grails · Mar 26, 2024 · 5912be5 · 5912be5
2 parents d17cb0b + aff63d7
commit 5912be5
Show file tree

Hide file tree

Showing 30 changed files with 240 additions and 291 deletions.
diff --git a/.github/workflows/gradle.yml b/.github/workflows/gradle.yml
@@ -6,22 +6,18 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        java: ['11']
     env:
       GIT_USER_NAME: puneetbehl
-      GIT_USER_EMAIL: behlp@objectcomputing.com
+      GIT_USER_EMAIL: behlp@unityfoundation.io
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
         with:
           token: ${{ secrets.GH_TOKEN }}
-      - uses: gradle/wrapper-validation-action@v1
       - name: Set up JDK
         uses: actions/setup-java@v3
         with:
-          java-version: ${{ matrix.java }}
+          java-version: 11
           distribution: 'adopt'
       - name: Publish Documentation
         uses: gradle/gradle-build-action@v2

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -8,13 +8,12 @@ on:
 jobs:
   release:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        java: ['11']
+    permissions:
+      contents: write    
     env:
-      BETA: ${{ contains(github.event.inputs.gorm_version, 'M') || contains(github.event.inputs.gorm_version, 'RC') }}
+      BETA: ${{ contains(github.event.inputs.gorm_version, 'M') }}
       GIT_USER_NAME: puneetbehl
-      GIT_USER_EMAIL: behlp@objectcomputing.com
+      GIT_USER_EMAIL: behlp@unityfoundation.io
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
@@ -24,35 +23,12 @@ jobs:
         uses: actions/setup-java@v3
         with:
           distribution: 'adopt'
-          java-version: ${{ matrix.java }}
+          java-version: 11
       - name: Extract branch name
-        if: success() && github.event_name == 'workflow_dispatch'
         id: extract_branch
         run: echo "value=${GITHUB_REF:11}" >> $GITHUB_OUTPUT
-      - name: Asset Path
-        if: success() && github.event_name == 'workflow_dispatch'
-        id: asset_path
-        uses: haya14busa/action-cond@v1
-        with:
-          cond: ${{ env.BETA == '' || env.BETA == 'false' }}
-          if_true: ${{ env.PATH_PREFIX }}-${{ github.event.inputs.gorm_version }}.zip
-          if_false: ${{ env.PATH_PREFIX }}-${{ github.event.inputs.gorm_version }}.zip
-        env:
-          PATH_PREFIX: "./build/distributions/gorm-docs"
-      - name: Create Release
-        if: success() && github.event_name == 'workflow_dispatch'
-        id: create_release
-        uses: actions/create-release@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          tag_name: v${{ github.event.inputs.gorm_version }}
-          release_name: ${{ github.event.inputs.gorm_version }}
-          draft: false
-          prerelease: ${{ env.BETA }}
       - name: Run pre-release
-        if: success() && github.event_name == 'workflow_dispatch'
-        uses: grails/github-actions/pre-release@main
+        uses: grails/github-actions/pre-release@v2
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
         env:
@@ -67,18 +43,21 @@ jobs:
           TAGGED_VERSION: v${{ github.event.inputs.gorm_version }}
           GRADLE_ENTERPRISE_ACCESS_KEY: ${{ secrets.GRADLE_ENTERPRISE_ACCESS_KEY }}
           GRADLE_ENTERPRISE_BUILD_CACHE_NODE_USER: ${{ secrets.GRADLE_ENTERPRISE_BUILD_CACHE_NODE_USER }}
-          GRADLE_ENTERPRISE_BUILD_CACHE_NODE_KEY: ${{ secrets.GRADLE_ENTERPRISE_BUILD_CACHE_NODE_KEY }}         
-      - name: Upload Release Asset
-        if: success() && github.event_name == 'workflow_dispatch'
-        id: upload-release-asset
-        uses: actions/upload-release-asset@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GRADLE_ENTERPRISE_BUILD_CACHE_NODE_KEY: ${{ secrets.GRADLE_ENTERPRISE_BUILD_CACHE_NODE_KEY }}          
+      - name: Create Release With Assets
+        uses: ncipollo/release-action@v1
+        id: create_release
+        if: success()
         with:
-          upload_url: ${{ steps.create_release.outputs.upload_url }}
-          asset_path: ${{ steps.asset_path.outputs.value }}
-          asset_name: gorm-docs.zip
-          asset_content_type: application/zip
+          tag: v${{ github.event.inputs.gorm_version }}
+          name: ${{ github.event.inputs.gorm_version }}
+          prerelease: ${{ env.BETA }}
+          artifacts: ${{ env.PATH_PREFIX }}-${{ github.event.inputs.gorm_version }}.zip
+          artifactContentType: application/zip  
+          generateReleaseNotes: true   
+          token: ${{ secrets.GITHUB_TOKEN }} 
+        env:
+          PATH_PREFIX: "./build/distributions/gorm-docs"
       - name: Determine docs target repository
         if: success()
         uses: haya14busa/action-cond@v1
@@ -101,10 +80,11 @@ jobs:
           COMMIT_NAME: ${{ env.GIT_USER_NAME }}
       - name: Run post-release
         if: success()
-        uses: grails/github-actions/post-release@main
+        uses: grails/github-actions/post-release@v2
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
         env:
           TARGET_BRANCH: ${{ steps.extract_branch.outputs.value }}
+          RELEASE_VERSION: ${{ github.event.inputs.gorm_version }}
           RELEASE_URL: "https://api.github.com/repos/grails/gorm-docs/releases/${{ steps.create_release.outputs.id }}"
-          SNAPSHOT_SUFFIX: -SNAPSHOT
+          SNAPSHOT_SUFFIX: -SNAPSHOT
diff --git a/build.gradle b/build.gradle
@@ -114,6 +114,8 @@ allprojects { project ->
                 'version': project.version,
                 'imagesdir': 'images',
                 'sourcedir': "${project.projectDir}/src/main/groovy"
+
+        baseDirFollowsSourceFile()
     }
 
     task copyDocs(type: Copy, dependsOn: asciidoctor) {

diff --git a/developer/src/docs/asciidoc/gettingStarted.adoc b/developer/src/docs/asciidoc/gettingStarted.adoc
@@ -2,70 +2,46 @@
 === Checking out and Building 
 
 
-The project is currently hosted on Github at [https://github.com/grails/grails-data-mapping].
+The project is https://github.com/grails/grails-data-mapping[hosted on GitHub].
 
 You are free to fork the project from there or clone it anonymously using git:
 
-[source,groovy]
 ----
-git clone git@github.com:grails/grails-data-mapping.git
+git clone https://github.com/grails/grails-data-mapping.git
 cd grails-data-mapping
 ----
 
-The project has a https://gradle.org[Gradle] build. You will need Intellij 15 or greater to work with the source code.
-
-Use the Intellij 15 Gradle tooling to import the project.
-
+The project has a https://gradle.org[Gradle] build.
 
 To build the project you can run the `assemble` task:
 
-[source,groovy]
 ----
 ./gradlew assemble
 ----
 
 To install the jar files for the various subprojects into your local Maven repository you can run:
 
-[source,groovy]
 ----
-./gradlew install
+./gradlew publishToMavenLocal
 ----
 
-To build all of the documentation run the command:
-
-[source,groovy]
-----
-./gradlew allDocs
-----
-
-Documentation will produced in the `build/docs` directory.
-
-NOTE: If you experience PermGen errors when building documentation you may need to increase the JVM permgen inside GRADLE_OPTS
-
-
 === Project Structure
 
-
 The project is essentially a multi-project Gradle build. There is a core API and then subprojects that implement that API. The core API subprojects include:
 
 * `grails-datastore-core` - The core API, this provides core interfaces for implementing a GORM provider
-* `grails-datastore-gorm` - The runtime meta-programming and AST transformation infrastructure behind GORM. Also provides end users APIs like `grails.gorm.CriteriaBuilder` and `grails.gorm.DetachedCriteria` 
+* `grails-datastore-gorm` - The runtime meta-programming and AST transformation infrastructure behind GORM. This also provides end users with APIs like `grails.gorm.CriteriaBuilder` and `grails.gorm.DetachedCriteria`
 * `grails-datastore-gorm-support` - Support classes for easing the writing of a GORM plugin for Grails
 * `grails-datastore-gorm-tck` - The TCK that includes hundreds of Spock specifications that a GORM implementation will need to pass
 * `grails-datastore-web` - Classes required to integrate GORM into a web tier
 
-Beyond these core subprojects there are implementations for various datastores. For example:
-
-* `grails-datastore-mongodb/grails-datastore-gorm-hibernate` - GORM for Hibernate
-* `grails-datastore-mongodb/grails-datastore-gorm-mongo` - GORM for MongoDB project [https://grails.org/plugin/mongodb]
-* `grails-datastore-neo4j` - GORM for Neo4j project [https://grails.org/plugin/neo4j]
-* `grails-datastore-redis/grails-datastore-gorm-redis` - GORM for Redis project [https://grails.org/plugin/redis]
-* `grails-datastore-cassandra/grails-datastore-gorm-cassandra` - GORM for Cassandra project [https://grails.org/plugin/cassandra]
-
-
-The documentation for each implementation is kept in the documentation subprojects that start with `grails-documentation`. There are documentation projects for the core API, MongoDB, Neo4j, Redis, and Cassandra.
-
-Finally the Grails 3 plugins that are used to distribute the GORM implementations to end users can be found in the `grails-plugins` directory and the `grails2-plugins` directory for Grails 2.x.
+In addition to this, there are separate projects of GORM implementations for various datastores:
 
+* https://github.com/grails/gorm-hibernate4[GORM for Hibernate 4]
+* https://github.com/grails/gorm-hibernate5[GORM for Hibernate 5]
+* https://github.com/grails/gorm-mongodb[GORM for MongoDB]
+* https://github.com/grails/gorm-neo4j[GORM for Neo4j]
+* https://github.com/grails/gorm-redis[GORM for Redis]
+* https://github.com/grails/gorm-cassandra[GORM for Cassandra]
 
 
diff --git a/developer/src/docs/asciidoc/index.adoc b/developer/src/docs/asciidoc/index.adoc
@@ -1,9 +1,13 @@
-= GORM Developer Guide
-Graeme Rocher
 :imagesdir: ./images
 :source-highlighter: coderay
+:toc: left
+:toc-title: GORM Developer Guide
+:numbered:
 :last-update-label!:
 
+= GORM Developer Guide
+Graeme Rocher
+
 [[introduction]]
 == Introduction
 
@@ -55,6 +59,6 @@ include::understandingApi/gormApis.adoc[]
 include::testing.adoc[]
 
 [[stepByStep]]
-== Step by Step Guide to Creating an Implementation
+== Step-by-Step Guide to Creating an Implementation
 
 include::stepByStep.adoc[]
diff --git a/developer/src/docs/asciidoc/introduction.adoc b/developer/src/docs/asciidoc/introduction.adoc
@@ -1,8 +1,8 @@
-This documentation describes the GORM API mechanics and how a datastore implementation can be built to interface to any database providing a GORM API onto it. This documentation is mainly targeted at developers interested in creating implementations of GORM ontop of alternative datastores.
+This documentation describes the GORM API mechanics and how a datastore implementation can be built to interface to any database providing a GORM API onto it. This documentation is mainly targeted at developers interested in creating implementations of GORM on top of alternative datastores.
 
 As of this writing the project has several implementations of GORM against a variety of different datastore implementations. Current implementations include:
 
-* Hibernate 3,4 and 5
+* Hibernate 3, 4 and 5
 * MongoDB
 * Redis
 * Neo4j

diff --git a/developer/src/docs/asciidoc/stepByStep.adoc b/developer/src/docs/asciidoc/stepByStep.adoc
@@ -1,14 +1,13 @@
-To get started with your a new GORM implementation the following steps are required:
+To get started with a new GORM implementation, the following steps are required:
 
 
 === Initial Directory Creation
 
 
-[source,groovy]
 ----
-$ git clone git@github.com:grails/grails-data-mapping.git
-$ cd grails-data-mapping
-$ mkdir grails-datastore-gorm-xyz
+git clone https://github.com/grails/grails-data-mapping.git
+cd grails-data-mapping
+mkdir grails-datastore-gorm-xyz
 ----
 
 
@@ -17,31 +16,29 @@ $ mkdir grails-datastore-gorm-xyz
 
 Create build.gradle:
 
-[source,groovy]
 ----
-$ vi grails-datastore-gorm-xyz/build.gradle
+vi grails-datastore-gorm-xyz/build.gradle
 ----
 
 With contents:
 
 [source,groovy]
 ----
 dependencies {
-    compile project(':grails-datastore-gorm'),
+    implementation project(':grails-datastore-gorm'),
             project(':grails-datastore-web'),
             project(':grails-datastore-gorm-support')
             
-    testCompile project(':grails-datastore-gorm-tck')
+    testImplementation project(':grails-datastore-gorm-tck')
     testRuntime "javax.servlet:javax.servlet-api:$servletApiVersion"
 
 }
 ----
 
 Add new project to settings.gradle in root project:
 
-[source,groovy]
 ----
-$ vi settings.gradle
+vi settings.gradle
 ----
 
 Changes shown below:
@@ -51,33 +48,30 @@ Changes shown below:
 // GORM Implementations
 'grails-datastore-gorm-neo4j',
 'grails-datastore-gorm-xyz',
-....
+...
 ----
 
 
 === Create Project Source Directories
 
 
-[source,groovy]
 ----
-$ mkdir grails-datastore-gorm-xyz/src/main/groovy
-$ mkdir grails-datastore-gorm-xyz/src/test/groovy
+mkdir grails-datastore-gorm-xyz/src/main/groovy
+mkdir grails-datastore-gorm-xyz/src/test/groovy
 ----
 
 
-=== Generate IDE Project Files and Import into IDE
+=== Generate IDE Project Files and Import into IDE (Optional)
 
 
-[source,groovy]
 ----
-$ gradlew grails-datastore-gorm-xyz:idea
+./gradlew grails-datastore-gorm-xyz:idea
 ----
 
 Or
 
-[source,groovy]
 ----
-$ gradlew grails-datastore-gorm-xyz:eclipse
+./gradlew grails-datastore-gorm-xyz:eclipse
 ----
 
 

diff --git a/developer/src/docs/asciidoc/testing.adoc b/developer/src/docs/asciidoc/testing.adoc
@@ -1,4 +1,4 @@
-The `grails-datastore-gorm-tck` project provides a few hundred tests that ensure a particular GORM implementation is compliant. To use the TCK you need to define a dependency on the TCK in the subprojects `build.gradle` file:
+The `grails-datastore-gorm-tck` project provides several hundred tests to guarantee that a particular GORM implementation is compliant. To use the TCK you need to define a dependency on the TCK in the subprojects `build.gradle` file:
 
 [source,groovy]
 ----
@@ -41,11 +41,11 @@ class Setup {
 }
 ----
 
-Some setup code has been omitted for clarity but basically the `Setup.groovy` class should initiase the `Datastore` and return a `Session` from the static `setup` method which gets passed a list of classes that need to be configured.
+Some setup code has been omitted for clarity, but essentially, the `Setup.groovy` class should initialize the `Datastore` and return a `Session` from the static setup method, which is passed a list of classes to configure.
 
-With this done all of the TCK tests will run against the subproject. If a particular test cannot be implemented because the underlying datastore doesn't support the feature then you can create a test that matches the name of the test that is failing and it will override said test.
+With this setup, all the TCK tests will be run against the subproject. If a specific test cannot be implemented due to the underlying datastore lacking support for a particular feature, you can create a test with the same name as the failing test, and that will then override the corresponding test in the TCK.
 
-For example SimpleDB doesn't support pagination so there is a `grails.gorm.tests.PagedResultSpec` class that overrides the one from the TCK. Each test is a Spock specification and Spock has an `Ignore` annotation that can be used to ignore a particular test:
+For example: SimpleDB doesn't support pagination. Add a `grails.gorm.tests.PagedResultSpec` class that overrides the one from the TCK. Each test is a Spock specification and Spock has an `Ignore` annotation that can be used to ignore a particular test:
 
 [source,groovy]
 ----

diff --git a/developer/src/docs/asciidoc/understandingApi.adoc b/developer/src/docs/asciidoc/understandingApi.adoc
@@ -1,9 +1,7 @@
 
 === Introduction
 
+The GORM Developer API is divided into a low-level API that implementors must implement for each specific datastore, and a set of higher-level APIs that enhance domain classes with features visible to regular users, such as dynamic finders, criteria queries, and so on.
 
-The GORM Developer API is split into a low-level API that implementors need to implement for each individual datastore and then set of higher level APIs that enhance domain classes with things regular users see such as dynamic finders, criteria queries and so on.
-
-The low-level API classes are found in the `grails-datastore-core` subproject, whilst the higher level APIs used to enhance domain classes are found in `grails-datastore-gorm`. In this section we will discuss the low-level API.
-
+The low-level API classes are located within the `grails-datastore-core` subproject, whereas the higher-level APIs used to enhance domain classes can be found in `grails-datastore-gorm`. In this section, we will discuss the low-level API.