You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+58-24Lines changed: 58 additions & 24 deletions
Original file line number
Diff line number
Diff line change
@@ -25,10 +25,9 @@ All types of contributions are encouraged and valued. See the [Table of Contents
25
25
26
26
> 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:
27
27
> - Star the project
28
-
> -Tweet about it
28
+
> -Talk about it on Social Media
29
29
> - Refer to this project in your project's readme
30
30
> - Mention the project at local meetups and tell your friends/colleagues
31
-
> -[Donate](https://opencollective.com/friends-of-grails) to the Friends of Grails initiative so others can work on the project.
32
31
33
32
<!-- omit in toc -->
34
33
## Table of Contents
@@ -68,7 +67,8 @@ If you then still feel the need to ask a question and need clarification, we rec
68
67
## I Want to Contribute
69
68
70
69
> ### Legal Notice <!-- omit in toc -->
71
-
> 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).
70
+
> When contributing to this project, you must agree that you have authored 100% of the content, that you have the
71
+
> necessary rights to the content and that the content you contribute may be provided under the project license.
72
72
73
73
### Reporting Bugs
74
74
@@ -142,23 +142,44 @@ One of the benefits of [GitHub](http://github.com) is the way that you can easil
142
142
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:
143
143
144
144
* A git client
145
-
* An Editor such as [IntelliJ](https://www.jetbrains.com/idea/).
145
+
* An Editor such as [IntelliJ](https://www.jetbrains.com/idea/)
146
+
* A JDK (17 or higher)
147
+
* A container runtime
146
148
147
-
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:
149
+
Once you have the pre-requisite packages installed, the next step is to download the Apache Grails source code, which is
150
+
hosted at [GitHub](http://github.com/apache/grails-core). This is a simple case of cloning the repository you're
151
+
interested in. For example, to get the core framework run:
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:
155
+
This will create a `grails-core` directory in your current working directory containing all the project source files.
156
+
The next step is setting up the JDK to use. Grails makes use of [SDKMAN!](https://sdkman.io/) for easy JDK setup. Each
157
+
Grails project should have a `.sdkmanrc` in it's root directory. Change to the `grails-core` directory and install the
158
+
preferred JDK by issuing the command:
152
159
153
160
sdk env .
154
161
162
+
##### 3. Building the Code
163
+
164
+
To build the code, without tests, simply run:
165
+
166
+
./gradlew build -PskipTests
167
+
168
+
If you encounter out of memory errors when trying to run the build, try adjusting Gradle build settings. For example:
Please note that a valid container runtime is required to run Grails Tests. The example above omits the tests so the
173
+
build will pass.
174
+
155
175
<!-- omit in toc -->
156
176
#### Testing Your Change
157
-
Grails has both local test coverage in the form of `unit` and `integration` tests.
158
177
159
-
To run the full suite of tests in `grails-core` execute:
178
+
Grails has test coverage in the form of `unit`, `integration`, and `functional` tests.
160
179
161
-
./gradlew check
180
+
To force a full run of the full suite of tests in `grails-core` execute:
181
+
182
+
./gradlew build --rerun-tasks
162
183
163
184
Check the test results & verify that the build completes successfully.
164
185
@@ -170,10 +191,13 @@ Sometimes it's useful to debug your local application to see what's going wrong.
170
191
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.
171
192
172
193
### Improving The Documentation
173
-
There are many aspects to [Grail's documentation](https://grails.org/documentation.html):
194
+
195
+
There are many aspects to [Grail's documentation](https://docs.grails.org/)
174
196
-[API](https://docs.grails.org/latest/api/) documentation in the code itself via javadoc & groovydoc.
175
-
-[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.
176
-
- Various how-to [Guides](https://guides.grails.org/index.html) from the [grails-guides](https://github.com/grails/grails-guides) project.
197
+
-[The Grails User Guide](https://docs.grails.org/latest/guide/single.html) from the `grails-doc` project in this
198
+
repository.
199
+
- Various how-to [Guides](https://guides.grails.org/index.html) from
200
+
the [grails-guides](https://github.com/grails-guides) Organization.
177
201
178
202
<!-- omit in toc -->
179
203
#### <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
183
207
184
208
<!-- omit in toc -->
185
209
#### <u>Building the Guide</u>
186
-
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:
187
-
188
-
$ git clone https://github.com/apache/grails-doc/
189
-
$ cd grails-doc
190
210
191
-
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.
211
+
If you want to make significant changes, such as changing the structure of the table of contents etc. then we recommend
212
+
you build the user guide. The source files can be found in the `grails-doc/src/en/guide` directory. Whilst the Table of
213
+
Contents (TOC) is defined in the `grails-doc/src/en/guide/toc.yml` file.
192
214
193
215
Each YAML key points to a Asciidoc template. For example consider the following YAML:
194
216
@@ -198,27 +220,39 @@ Each YAML key points to a Asciidoc template. For example consider the following
198
220
title: What's new in Grails 3.2?
199
221
...
200
222
201
-
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`.
223
+
The `introduction` key points to `grails-doc/src/en/guide/introduction.adoc`. The `title` key defines the title that is
224
+
dislayed in the TOC. Because `whatsNew` key is nested underneath the `introduction` key it points to
225
+
`grails-doc/src/en/guide/introduction/whatsNew.adoc`, which is nested in a directory called `introduction`.
202
226
203
227
Essentially, using the `toc.yml` file and the directory structure you can manipulate the structure of the user guide.
204
228
205
-
To generate the documentation run the `publishGuide` task:
229
+
To generate the documentation run the `publishGuide`in the `grails-doc`task:
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!
233
+
NOTE: In the above example we skip the `aggregateGroovydoc` task to speed up building of the guide, otherwise all
234
+
Groovydoc documentation will be built too!
210
235
211
-
Once the guide is built simply open the `build/docs/index.html` file in a browser to review your changes.
236
+
Once the guide is built simply open the `grails-doc/build/original-guide/index.html` file in a browser to review your
237
+
changes.
212
238
213
239
## Code Style
214
240
215
241
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).
216
242
217
243
### Commit Messages
218
-
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.
244
+
245
+
Grails makes use of [Release Drafter](https://github.com/release-drafter/release-drafter) to draft its release notes so
246
+
commit messages are important. They should follow the project's rules. While a change can be incrementally made under
247
+
many commits, pull requests should be squashed into a single, meaningful commit message.
219
248
220
249
### Change Review Process
221
-
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.
250
+
251
+
The Apache Grails project uses different review processes based on the change being made. We use both a
252
+
`Review then Commit` policy and a `Commit then Review` policy. These policies only apply to what we consider `protected`
253
+
branches - where a `protected` branch is a branch that will result in published code or tracks an Apache Grails release
254
+
version (i.e. 7.0.x is for the Apache Grails 7 release). Development will often occur in side branches without review
255
+
and the review will be performed at the time of merging those changes into a `protected` branch.
222
256
223
257
Concerning when a review is required for a `protected` branch:
Copy file name to clipboardExpand all lines: README.md
+81-42Lines changed: 81 additions & 42 deletions
Original file line number
Diff line number
Diff line change
@@ -14,50 +14,102 @@ See the License for the specific language governing permissions and
14
14
limitations under the License.
15
15
-->
16
16
17
-
# Grails
18
-
[](https://ge.grails.org/scans)
[Apache Grails](https://grails.org/) is a framework used to build web applications with
30
+
the [Apache Groovy](https://groovy-lang.org/) programming language. Releases prior to 7.0.0 were outside of the Apache
31
+
Software Foundation. The core framework is very extensible and there are numerous [plugins](https://plugins.grails.org/)
32
+
available that provide easy integration of add-on features. To assist in getting started, various Application generators
33
+
exist and are provided by the Apache Grails team.
34
+
35
+
## Getting help
36
+
37
+
Ask questions on the [Grails User Mailing List](https://lists.apache.org/[email protected])
38
+
Join the discussions on [Slack](https://slack.grails.org/)
39
+
Check the [Documentation](https://docs.grails.org/) for your preferred Apache Grails version.
40
+
Check for a [Grails Guide](https://github.com/grails-guides/).
41
+
42
+
## Application Generation
43
+
44
+
The only requirement for Apache Grails is the Java Development Kit (JDK). Once a JDK is installed there are many ways to
45
+
get started. The preferred way to get started is to use [Grails Forge](https://start.grails.org). Alternatively, offline
46
+
CLI applications exist to assist in Application generation. Instructions for them follow.
47
+
48
+
### Wrapper
49
+
50
+
The Apache Grails Wrapper is a tiny distribution (25KB) that can manage larger sized CLIs for Grails. It consists of a
51
+
`grailsw` shell script, a `grailsw.bat` batch script, and the jar file `grails-wrapper.jar`. It can be downloaded from
52
+
the latest [Github Release](https://github.com/apache/grails-core/releases) page starting with 7.0.0-M4 & it is included
53
+
in any created project. The wrapper is used to either create an Apache Grails Application or to run commands in an
54
+
existing Grails Application directory. The wrapper is generally meant to be forward compatible and downloads the Apache
55
+
Grails CLIs to the directory `$HOME/.grails/wrapper`.
56
+
57
+
#### Wrapper - Creating a Apache Grails Application
58
+
59
+
To create an Apache Grails Application with the wrapper follow these steps:
21
60
22
-
### Getting help
23
-
Join the discussions on [Slack](https://slack.grails.org/)
24
-
Ask questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/grails)
61
+
1. Extract the wrapper to your preferred location.
62
+
2. Set the environment variable `PREFERRED_GRAILS_VERSION` to the preferred version.
63
+
3. Run the wrapper command `grailsw -t forge create-app` to create a new Apache Grails Application.
25
64
26
-
## What is Grails?
27
-
[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.
65
+
Please note, that the wrapper supports either the legacy `Apache Grails Shell` or the newer `Apache Grails Forge` CLI.
66
+
For more detailed information about it, see the [documentation](https://docs.grails.org/snapshot/index.html).
28
67
29
-
[Commercial support](https://grails.org/support.html) options are available.
68
+
#### Wrapper - Running Commands inside a Apache Grails Project
30
69
31
-
## Getting Started
70
+
For running commands, the Grails Wrapper will always pull the Apache Grails version from `gradle.properties` and ignore
71
+
any environment variables. Type `grailsw -t shell help` to see the available commands. For more detailed information
72
+
about it, see the [documentation](https://docs.grails.org/snapshot/index.html).
32
73
33
-
You need a Java Development Kit (JDK) installed, but it is not necessary to install Groovy because it's bundled with the Grails distribution.
74
+
### grails-shell-cli
34
75
35
-
It's recommended to use the [SDKMAN!](https://sdkman.io/) tool to install & manage multiple Grails version.
36
-
Alternatively, visit https://grails.org/download.html for other install options. If downloading the binary, the only
37
-
requirement is it be added to your path.
76
+
The legacy Apache Grails CLI is the command line interface that IntelliJ uses to interact with existing Apache Grails
77
+
Applications. It can be used to generate applications or it can be used to interact with existing ones. To use it,
78
+
download it to your preferred location from the [grails-forge](https://github.com/apache/grails-forge/releases) release
79
+
page. You can use the command `./grails-shell-cli help` to see what's possible.
38
80
39
-
To create your first Grails Application, you can use [Grails Forge](https://start.grails.org) or you can use the command
40
-
line. For legacy reasons, there exists 2 ways to generate Grails applications. `Grails Forge` and `Grails Shell`. The
41
-
grails binary allows you to use either to generate an app.
81
+
### grails-forge-cli
42
82
43
-
For example purposes, using the legacy shell:
83
+
The newer Apache Grails CLI is available from the [grails-forge](https://github.com/apache/grails-forge/releases)
84
+
release page. You can use the command `./grails-forge-cli --help` to see what's possible.
44
85
45
-
grails create-app sampleapp
46
-
cd sampleapp
47
-
./gradlew bootRun
86
+
### SDKMAN
48
87
49
-
To build Grails, clone this GitHub repository and execute the build Gradle target:
88
+
If managing multiple, local copies of the Grails CLI, it is recommended to use [SDKMAN!](https://sdkman.io/). Assuming
89
+
SDKMAN is installed, this command would install the 7.0.0-M4 version:
0 commit comments