(groovy) branch master updated: minor refactor: flesh out some minor details

[pa...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

paulk-asert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/groovy.git


The following commit(s) were added to refs/heads/master by this push:
     new c9a0098b29 minor refactor: flesh out some minor details
c9a0098b29 is described below

commit c9a0098b29a6c0fbaf9368e02ecf3dbe9cc13b3b
Author: Paul King <pa...@asert.com.au>
AuthorDate: Thu Apr 23 11:08:15 2026 +1000

    minor refactor: flesh out some minor details
---
 CONTRIBUTING.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 65 insertions(+), 4 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 64c7e2908a..f266c114a6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,10 +16,71 @@ limitations under the License.
 
 # Contributing
 
-Please visit the
-[project development website](https://groovy.apache.org/)
-to find out more about contributing to the project.
-We welcome all contributors.
+We welcome all contributors. This file covers code contributions to the
+Groovy repository. For ways to contribute that don't involve changing the
+code — helping on the mailing lists, reporting issues, writing blog posts,
+or contributing to the reference documentation on the website — see the
+[project contribute page](https://groovy.apache.org/contribute.html).
+
+## Building and testing
+
+JDK 17 or later is required. The canonical build instructions live in
+[`README.adoc`](README.adoc). The short form:
+
+```
+./gradlew clean dist                                # full build
+./gradlew test                                      # run tests
+./gradlew :<module>:test --tests <TestClassName>    # run a single test
+```
+
+Use the Gradle wrapper (`./gradlew` / `gradlew.bat`); do not invoke a
+system `gradle`. Most modern IDEs open the Gradle project directly.
+
+Run `./gradlew test` locally before sending a pull request. All tests
+should be green.
+
+## Documentation
+
+Documentation is a first-class deliverable, not an afterthought. When
+contributing code, please treat documentation as part of the change:
+
+- **Docs live in the code repository.** AsciiDoc sources are under
+  `src/spec/doc/` for cross-cutting material and
+  `subprojects/<module>/src/spec/doc/` for module-specific material.
+  Each large module should have at least one AsciiDoc file covering
+  what it offers.
+- **Examples are executable.** Code snippets in the AsciiDoc are
+  `include::`'d from real Groovy files under a matching `src/spec/test/`
+  directory, so every example compiles and runs as part of the build.
+  When you add an example, make it executable the same way — see any
+  existing `.adoc` file under `subprojects/*/src/spec/doc/` for the
+  pattern.
+- **Documentation changes ship with the code.** If a pull request adds,
+  changes, or removes user-visible behaviour, the relevant AsciiDoc and
+  test examples should change in the same pull request. Reviewers will
+  ask.
+- **Groovydoc is part of the public API.** Public classes and methods
+  need accurate Groovydoc/Javadoc. Match the style of existing classes
+  in the module you're editing.
+
+Cross-version reference documentation, the GDK, and the website itself
+live in the separate [`groovy-website`](https://github.com/apache/groovy-website)
+repository; see the [project contribute page](https://groovy.apache.org/contribute.html)
+for how to contribute there.
+
+## Submitting a pull request
+
+1. Fork <https://github.com/apache/groovy> and create a feature branch.
+2. Reference the JIRA issue in commits, for example
+   `GROOVY-12345: short description`.
+3. Keep commits focused. A bug fix, a refactor, and a formatting pass
+   are three separate commits (or pull requests), not one.
+4. Run `./gradlew test` locally and confirm it passes.
+5. Open a pull request against `master`.
+
+GitHub's [fork a repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo)
+and [creating a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
+guides cover the generic git mechanics.
 
 ## Using AI tooling