Documentation Updates for Apache

.github/workflows/gradle.yml

@@ -13,7 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-name: "Java CI"
+name: "CI"
 on:
   push:
     branches:

CODE_OF_CONDUCT.md

@@ -0,0 +1,8 @@
+# Code of Conduct
+
+Apache Grails (Incubating) follows the ASF [Code of
+Conduct](https://www.apache.org/foundation/policies/conduct).
+
+If you observe behavior that violates those rules please follow the
+[ASF reporting
+guidelines](https://www.apache.org/foundation/policies/conduct#reporting-guidelines).

CONTRIBUTING.md

@@ -25,10 +25,9 @@ All types of contributions are encouraged and valued. See the [Table of Contents
 
 > And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about:
 > - Star the project
-> - Tweet about it
+> - Talk about it on Social Media
 > - Refer to this project in your project's readme
 > - Mention the project at local meetups and tell your friends/colleagues
-> - [Donate](https://opencollective.com/friends-of-grails) to the Friends of Grails initiative so others can work on the project.
 
 <!-- omit in toc -->
 ## Table of Contents
@@ -68,7 +67,8 @@ If you then still feel the need to ask a question and need clarification, we rec
 ## I Want to Contribute
 
 > ### Legal Notice <!-- omit in toc -->
-> When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license.  All committers must sign the project's CLA.  More detailed requirements are available in the project's [CLA](https://cla-assistant.io/apache/grails-core).
+> When contributing to this project, you must agree that you have authored 100% of the content, that you have the
+> necessary rights to the content and that the content you contribute may be provided under the project license.
 
 ### Reporting Bugs
 
@@ -142,23 +142,44 @@ One of the benefits of [GitHub](http://github.com) is the way that you can easil
 If you're interested in contributing fixes and features to any part of grails, you will have to learn how to get hold of the project's source, build it and test it with your own applications. Before you start, make sure you have:
 
 * A git client
-* An Editor such as [IntelliJ](https://www.jetbrains.com/idea/).  
+* An Editor such as [IntelliJ](https://www.jetbrains.com/idea/)
+* A JDK (17 or higher)
+* A container runtime
 
-Once you have the pre-requisite packages installed, the next step is to download the Grails source code, which is hosted at [GitHub](http://github.com) in several repositories owned by the ["grails" GitHub user](http://github.com/grails). This is a simple case of cloning the repository you're interested in. For example, to get the core framework run:
+Once you have the pre-requisite packages installed, the next step is to download the Apache Grails source code, which is
+hosted at [GitHub](http://github.com/apache/grails-core). This is a simple case of cloning the repository you're
+interested in. For example, to get the core framework run:
 
     git clone http://github.com/apache/grails-core.git
 
-This will create a `grails-core` directory in your current working directory containing all the project source files. The next step is setting up the JDK to use.  Grails makes use of [SDKMAN!](https://sdkman.io/) for easy JDK setup.  Each Grails project should have a `.sdkmanrc` in it's root directory.  Change to the `grails-core` directory and install the preferred JDK by issuing the command:
+This will create a `grails-core` directory in your current working directory containing all the project source files.
+The next step is setting up the JDK to use. Grails makes use of [SDKMAN!](https://sdkman.io/) for easy JDK setup. Each
+Grails project should have a `.sdkmanrc` in it's root directory. Change to the `grails-core` directory and install the
+preferred JDK by issuing the command:
 
     sdk env .
 
+##### 3. Building the Code
+
+To build the code, without tests, simply run:
+
+    ./gradlew build -PskipTests
+
+If you encounter out of memory errors when trying to run the build, try adjusting Gradle build settings. For example:
+
+    export GRADLE_OPTS="-Xmx2G -Xms2G -XX:NewSize=512m -XX:MaxNewSize=512m"
+
+Please note that a valid container runtime is required to run Grails Tests. The example above omits the tests so the
+build will pass.
+
 <!-- omit in toc -->
 #### Testing Your Change
-Grails has both local test coverage in the form of `unit` and `integration` tests.
 
-To run the full suite of tests in `grails-core` execute:
+Grails has test coverage in the form of `unit`, `integration`, and `functional` tests.
 
-    ./gradlew check
+To force a full run of the full suite of tests in `grails-core` execute:
+
+    ./gradlew build --rerun-tasks
 
 Check the test results & verify that the build completes successfully.
 
@@ -170,10 +191,13 @@ Sometimes it's useful to debug your local application to see what's going wrong.
 By default, Grails forks a JVM to run the application. The `-debug-jvm` argument causes the debugger to be associated with the forked JVM.  You can then attach your debugger as proceed as normal.
 
 ### Improving The Documentation
-There are many aspects to [Grail's documentation](https://grails.org/documentation.html): 
+
+There are many aspects to [Grail's documentation](https://docs.grails.org/)
 - [API](https://docs.grails.org/latest/api/) documentation in the code itself via javadoc & groovydoc.
-- [The Grails User Guide](https://docs.grails.org/6.2.1/guide/single.html) from the [grails-doc](https://github.com/apache/grails-doc) project.
-- Various how-to [Guides](https://guides.grails.org/index.html) from the [grails-guides](https://github.com/grails/grails-guides) project.
+- [The Grails User Guide](https://docs.grails.org/latest/guide/single.html) from the `grails-doc` project in this
+  repository.
+- Various how-to [Guides](https://guides.grails.org/index.html) from
+  the [grails-guides](https://github.com/grails-guides) Organization.
 
 <!-- omit in toc -->
 #### <u>Improving the User Guide</u>
@@ -183,12 +207,10 @@ This will link to the GitHub edit screen where you can make changes, preview the
 
 <!-- omit in toc -->
 #### <u>Building the Guide</u>
-If you want to make significant changes, such as changing the structure of the table of contents etc. then we recommend you build the user guide. To do that simply checkout the sources from GitHub:
-
-    $ git clone https://github.com/apache/grails-doc/
-    $ cd grails-doc
 
-The source files can be found in the `src/en/guide` directory. Whilst the Table of Contents (TOC) is defined in the `src/en/guide/toc.yml` file.
+If you want to make significant changes, such as changing the structure of the table of contents etc. then we recommend
+you build the user guide. The source files can be found in the `grails-doc/src/en/guide` directory. Whilst the Table of
+Contents (TOC) is defined in the `grails-doc/src/en/guide/toc.yml` file.
 
 Each YAML key points to a Asciidoc template. For example consider the following YAML:
 
@@ -198,27 +220,39 @@ Each YAML key points to a Asciidoc template. For example consider the following
     title: What's new in Grails 3.2?
     ...
 
-The `introduction` key points to `src/en/guide/introduction.adoc`. The `title` key defines the title that is dislayed in the TOC. Because `whatsNew` key is nested underneath the `introduction` key it points to `src/en/guide/introduction/whatsNew.adoc`, which is nested in a directory called `introduction`.
+The `introduction` key points to `grails-doc/src/en/guide/introduction.adoc`. The `title` key defines the title that is
+dislayed in the TOC. Because `whatsNew` key is nested underneath the `introduction` key it points to
+`grails-doc/src/en/guide/introduction/whatsNew.adoc`, which is nested in a directory called `introduction`.
 
 Essentially, using the `toc.yml` file and the directory structure you can manipulate the structure of the user guide.
 
-To generate the documentation run the `publishGuide` task:
+To generate the documentation run the `publishGuide` in the `grails-doc` task:
 
-    ./gradlew publishGuide -x apiDocs
+    ./gradlew :grails-doc:publishGuide -x aggregateGroovydoc
 
-NOTE: In the above example we skip the `apiDocs` task to speed up building of the guide, otherwise all Groovydoc documentation will be built too!
+NOTE: In the above example we skip the `aggregateGroovydoc` task to speed up building of the guide, otherwise all
+Groovydoc documentation will be built too!
 
-Once the guide is built simply open the `build/docs/index.html` file in a browser to review your changes.
+Once the guide is built simply open the `grails-doc/build/original-guide/index.html` file in a browser to review your
+changes.
 
 ## Code Style
 
 Grails code style mostly mirrors the Spring Framework's [Style Guide](https://github.com/spring-projects/spring-framework/blob/main/CONTRIBUTING.md#source-code-style).  We are currently working on a more detailed proposal under ticket [#13754](https://github.com/apache/grails-core/issues/13754).
 
 ### Commit Messages
-Grails makes use of [Release Drafter](https://github.com/release-drafter/release-drafter) to draft its release notes so commit messages are important.  They should follow the project's rules.  While a change can be incrementally made under many commits, pull requests should be squashed into a single, meaningful commit message.
+
+Grails makes use of [Release Drafter](https://github.com/release-drafter/release-drafter) to draft its release notes so
+commit messages are important. They should follow the project's rules. While a change can be incrementally made under
+many commits, pull requests should be squashed into a single, meaningful commit message.
 
 ### Change Review Process
-The Grails project uses different review processes based on the change being made.  We use both a `Review then Commit` policy and a `Commit then Review` policy.  These policies only apply to what we consider `protected` branches - where a `protected` branch is a branch that will result in published code or tracks a Grails release version (i.e. 7.0.x is for the Grails 7 release).  Development will often occur in side branches without review and the review will be performed at the time of merging those changes into a `protected` branch.
+
+The Apache Grails project uses different review processes based on the change being made. We use both a
+`Review then Commit` policy and a `Commit then Review` policy. These policies only apply to what we consider `protected`
+branches - where a `protected` branch is a branch that will result in published code or tracks an Apache Grails release
+version (i.e. 7.0.x is for the Apache Grails 7 release). Development will often occur in side branches without review
+and the review will be performed at the time of merging those changes into a `protected` branch.
 
 Concerning when a review is required for a `protected` branch:
 * Build Related Changes - `Commit then Review`

README.md

@@ -14,50 +14,103 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
-# Grails
-[![Revved up by Develocity](https://img.shields.io/badge/Revved%20up%20by-Develocity-06A0CE?logo=Gradle&labelColor=02303A)](https://ge.grails.org/scans)
-[![Java CI](https://github.com/apache/grails-core/actions/workflows/gradle.yml/badge.svg?event=push)](https://github.com/apache/grails-core/actions/workflows/gradle.yml)
+# Apache Grails (Incubating)
+
+[![Documentation](https://img.shields.io/badge/Documentation-595959)](https://docs.grails.org)
+[![Develocity](https://img.shields.io/badge/Develocity-06A0CE?logo=Gradle&labelColor=06A0CE)](https://ge.grails.org/scans)
+[![CI](https://github.com/apache/grails-core/actions/workflows/gradle.yml/badge.svg?event=push)](https://github.com/apache/grails-core/actions/workflows/gradle.yml)
 [![Groovy Joint Validation Build](https://github.com/apache/grails-core/actions/workflows/groovy-joint-workflow.yml/badge.svg?event=push)](https://github.com/apache/grails-core/actions/workflows/groovy-joint-workflow.yml)
+[![Users Mailing List](https://img.shields.io/badge/Users_Mailing_List-feb571)](https://lists.apache.org/[email protected])
+[![Dev Mailing List](https://img.shields.io/badge/Dev_Mailing_List-feb571)](https://lists.apache.org/[email protected])
+[![Slack](https://img.shields.io/badge/Join_Slack-e01d5a)](https://slack.grails.org/)
+[![GitHub Discussions](https://img.shields.io/github/discussions/apache/grails-core)](https://github.com/apache/grails-core/discussions)
+
+## Introduction
+
+[Apache Grails](https://grails.org/) is a framework used to build web applications with
+the [Apache Groovy](https://groovy-lang.org/) programming language. Releases prior to 7.0.0 were outside of the Apache
+Software Foundation. The core framework is very extensible and there are numerous [plugins](https://plugins.grails.org/)
+available that provide easy integration of add-on features. To assist in getting started, various Application generators
+exist and are provided by the Apache Grails team.
+
+## Getting help
+
+Ask questions on the [Grails User Mailing List](https://lists.apache.org/[email protected])
+Join the discussions on [Slack](https://slack.grails.org/)
+Check the [Documentation](https://docs.grails.org/) for your preferred Apache Grails version.
+Check for a [Grails Guide](https://github.com/grails-guides/).
+
+## Application Generation
+
+The only requirement for Apache Grails is the Java Development Kit (JDK). Once a JDK is installed there are many ways to
+get started. The preferred way to get started is to use [Grails Forge](https://start.grails.org). Alternatively, offline
+CLI applications exist to assist in Application generation. Instructions for them follow.
+
+### Wrapper
+
+The Apache Grails Wrapper is a tiny distribution (25KB) that can manage larger sized CLIs for Grails. It consists of a
+`grailsw` shell script, a `grailsw.bat` batch script, and the jar file `grails-wrapper.jar`. It can be downloaded from
+the latest [Github Release](https://github.com/apache/grails-core/releases) page starting with 7.0.0-M4 & it is included
+in any created project. The wrapper is used to either create an Apache Grails Application or to run commands in an
+existing Grails Application directory. The wrapper is generally meant to be forward compatible and downloads the Apache
+Grails CLIs to the directory `$HOME/.grails/wrapper`.
+
+#### Wrapper - Creating a Apache Grails Application
+
+To create an Apache Grails Application with the wrapper follow these steps:
 
-### Getting help
-Join the discussions on [Slack](https://slack.grails.org/)  
-Ask questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/grails)
+1. Extract the wrapper to your preferred location.
+2. Set the environment variable `PREFERRED_GRAILS_VERSION` to the preferred version.
+3. Run the wrapper command `grailsw -t forge create-app` to create a new Apache Grails Application.
 
-## What is Grails?
-[Grails](https://grails.org/) is a framework used to build web applications with the [Groovy](https://groovy-lang.org/) programming language. The core framework is very extensible and there are numerous [plugins](https://plugins.grails.org/) available that provide easy integration of add-on features.
+Please note, that the wrapper supports either the legacy `Apache Grails Shell` or the newer `Apache Grails Forge` CLI.
+For more detailed information about it, see the [documentation](https://docs.grails.org/snapshot/index.html).
 
-[Commercial support](https://grails.org/support.html) options are available.
+#### Wrapper - Running Commands inside a Apache Grails Project
 
-## Getting Started
+For running commands, the Grails Wrapper will always pull the Apache Grails version from `gradle.properties` and ignore
+any environment variables. Type `grailsw -t shell help` to see the available commands. For more detailed information
+about it, see the [documentation](https://docs.grails.org/snapshot/index.html).
 
-You need a Java Development Kit (JDK) installed, but it is not necessary to install Groovy because it's bundled with the Grails distribution.
+### grails-shell-cli
 
-It's recommended to use the [SDKMAN!](https://sdkman.io/) tool to install & manage multiple Grails version.
-Alternatively, visit https://grails.org/download.html for other install options. If downloading the binary, the only
-requirement is it be added to your path.
+The legacy Apache Grails CLI is the command line interface that IntelliJ uses to interact with existing Apache Grails
+Applications. It can be used to generate applications or it can be used to interact with existing ones. To use it,
+download it to your preferred location from the [grails-forge](https://github.com/apache/grails-forge/releases) release
+page. You can use the command `./grails-shell-cli help` to see what's possible.
 
-To create your first Grails Application, you can use [Grails Forge](https://start.grails.org) or you can use the command
-line. For legacy reasons, there exists 2 ways to generate Grails applications.  `Grails Forge` and `Grails Shell`. The
-grails binary allows you to use either to generate an app.
+### grails-forge-cli
 
-For example purposes, using the legacy shell:
+The newer Apache Grails CLI is available from the [grails-forge](https://github.com/apache/grails-forge/releases)
+release page. You can use the command `./grails-forge-cli --help` to see what's possible.
 
-	grails create-app sampleapp
-	cd sampleapp
-	./gradlew bootRun
+### SDKMAN
 
-To build Grails, clone this GitHub repository and execute the build Gradle target:
+If managing multiple, local copies of the Grails CLI, it is recommended to use [SDKMAN!](https://sdkman.io/). Assuming
+SDKMAN is installed, this command would install the 7.0.0-M4 version:
 
-    git clone https://github.com/apache/grails-core.git
-    cd grails-core
-    ./gradlew build -PskipTests
+     sdk install grails 7.0.0-M4
 
-If you encounter out of memory errors when trying to run the build, try adjusting Gradle build settings. For example:
+Apache Grails versions installed via SDKMAN! include the following commands `grails`, `grails-shell-cli`, &
+`grails-forge-cli`. The grails command simply delegates to forge or the legacy shell. For further information on SDKMAN,
+please see their [website](https://sdkman.io/).
 
-    export GRADLE_OPTS="-Xmx2G -Xms2G -XX:NewSize=512m -XX:MaxNewSize=512m"
+## Starting your Grails Application
 
-Please note that a valid container runtime is required to run Grails Tests. The example above omits the tests so the
-build will pass.
+Once your Apache Grails Application is created, you can start it with the command:
+
+    ./gradlew bootRun
+
+For further information, please consult the [documentation](https://docs.grails.org).
+
+## Building Grails
+
+For building Grails, please consult the [CONTRIBUTING.md](CONTRIBUTING.md) file.
+
+## Licensing
+
+Apache Grails is licensed under the Apache License, Version 2.0. For details, see
+the [LICENSE](./LICENSE).
 
 ## Performing a Release
 
@@ -70,16 +123,3 @@ https://opencollective.com/friends-of-grails
 
 This initiative is designed to complement the Apache project and the many contributions we get from our great community and supporters.
 
-
-## License
-
-Grails and Groovy are licensed under the terms of the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).
-
-***
-
-YourKit is kindly supporting Grails open source projects with its full-featured Java Profiler.
-YourKit, LLC is the creator of innovative and intelligent tools for profiling
-Java and .NET applications. Take a look at YourKit's leading software products:
-[YourKit Java Profiler](https://www.yourkit.com/java/profiler/features/) and
-[YourKit .NET Profiler](https://www.yourkit.com/.net/profiler/features/).
-