Skip to content
This repository was archived by the owner on Nov 6, 2025. It is now read-only.

Commit f2f521d

Browse files
ajoberstarajoberstar
committed
Add project documentation files
1 parent feb5a4b commit f2f521d

11 files changed

Lines changed: 463 additions & 2 deletions

File tree

‎.github/CONTRIBUTING.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Contributing to clojurephant-tooling
2+
3+
## Asking a question or getting help
4+
5+
The following is the preferred communication channel:
6+
7+
- Start a discussion in [Clojurephant Discussions](https://github.com/clojurephant/clojurephant/discussions)
8+
9+
The following are not actively monitored:
10+
11+
- Start a topic in [ClojureVerse Projects/gradle-clojure](https://clojureverse.org/c/projects/gradle-clojure)
12+
- Ask in [Clojurians Slack #gradle](http://clojurians.net/)
13+
14+
## Submitting a bug report or feature request
15+
16+
Create a new issue and fill out the template. Thanks for providing feedback on what's important to you as a user!
17+
18+
## Roadmap
19+
20+
See the [milestones](https://github.com/clojurephant/clojurephant-tooling/milestones) for details on planned features.
21+
22+
## Contributing documentation or code
23+
24+
Pull requests are very welcome. Thanks in advance for helping the project (that goes double for those of you updating documentation)!
25+
26+
- **For minor changes:** Go right ahead and submit a PR.
27+
- **For already open issues:** Comment in the issue that you'd like to help out on to ensure it's not already being worked on and to get guidance from the team.
28+
- **For new features:** Open an issue first detailing the feature. This will let the team provide feedback on how that feature can work best for the project.
29+
30+
### Development Setup
31+
32+
- Clone this repo.
33+
- Have a Java 8 or higher JDK installed.
34+
- If using Eclipse or Intellij:
35+
- Import the project as a Gradle project.
36+
- Import the Eclipse formatter preferences from `.gradle/eclipse-java-formatter.xml`. (See _Code Style_ for more information.)
37+
38+
### Project Structure
39+
40+
- Documentation is under `docs/`.
41+
- If you add a new page, make sure to add it to the following locations so that it's in the nav:
42+
- `docs/_includes/nav.md` (for the https://clojurephant.dev site)
43+
- `docs/cljdoc.edn` (for the https://cljdoc.org docs)
44+
- Modules:
45+
- Plugin itself is in `clojurephant-plugin/`
46+
- Test suite:
47+
- Functional Gradle tests (run against a range of Gradle versions) are in `clojurephant-plugin/src/compatTest`
48+
- Sample Projects:
49+
- These are separate repositories under the Clojurephant organization
50+
51+
### Gradle Resources
52+
53+
A few helpful resources if you're new to writing Gradle plugins:
54+
55+
- [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html), specifically:
56+
- [Designing Gradle plugins](https://guides.gradle.org/designing-gradle-plugins/) (see bottom of guide for links to further guides)
57+
- [Lazy task configuration](https://docs.gradle.org/current/userguide/lazy_configuration.html)
58+
- [Gradle DSL Reference](https://docs.gradle.org/current/dsl/)
59+
60+
### Testing Sample Projects
61+
62+
1. Clone the sample repo
63+
1. Use the project like normal to test its functionality
64+
65+
### Code Style
66+
67+
This project uses the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). Google provides [google-java-format](https://github.com/google/google-java-format) and an [Eclipse formatter profile](https://github.com/google/styleguide/blob/gh-pages/eclipse-java-google-style.xml) to help automate this. Both however have a weakness in how they line wrap, primarily for code that heavily uses lambdas. The style guide's text allows for more discretion in where line wrapping happens, but the automated ones can be overzealous. For this reason, we are using a modified version of the Eclipse profile that disables the automatic line wrapping.
68+
69+
The style is enforced using the [spotless](https://github.com/diffplug/spotless) plugin, which can also reformat your code to comply with the style with `./gradlew spotlessApply`.
70+
71+
You can import the Eclipse formatter settings `.gradle/eclipse-java-formatter.xml` to have your IDE respect the style.
72+
73+
## Maintainer/Collaborator Processes
74+
75+
### CI Configuration
76+
77+
clojurephant is built on GitHub Actions. This is configured in `.github/workflows/*.yaml`.
78+
79+
There are two workflows:
80+
81+
- `ci` - General build verification running on all branches and PRs on push:
82+
- Runs full `./gradlew check` and `./gradlew compatTest` test suites and style verification.
83+
- Runs on all supported Java versions (currently 8, 11, 17).
84+
- `release` - Publishing the plugin to Gradle's Plugin Portal and Clojars
85+
- When a tag is pushed, it will do a release/publish (i.e. _don't make a tag unless you're trying to release_).
86+
87+
### Updating our dependencies
88+
89+
To update the lock with the latest versions matching any ranges we specified:
90+
91+
```
92+
./gradlew lock --write-locks
93+
```
94+
95+
### Supporting new Gradle versions
96+
97+
The following task will update our lock files will the latest available versions that match the compatibility rules in our `stutter {}` block in `clojurephant-plugin/build.gradle`.
98+
99+
```
100+
./gradlew stutterWriteLocks
101+
```
102+
103+
The `stutter {}` block can also be used to change the ranges we support. See [stutter's documentation](https://github.com/ajoberstar/gradle-stutter) for details.
104+
105+
### Release Process
106+
107+
We use [reckon](https://github.com/ajoberstar/reckon) to manage our versioning and tagging. There is no version number stored in the build file, reckon will determine this automatically from the project history and user input.
108+
109+
We have 3 release stages:
110+
111+
- `beta` - significant functionality that we'd like to release but the version isn't feature-complete yet
112+
- `rc` - intended as a `final` release, but want to provide an opportunity for bug testing
113+
- `final` - no known or significant bugs were found in the rc, and it's ready for general consumption
114+
115+
To generate a release:
116+
117+
- (For `rc` or `final`) Make sure all issues in [GitHub milestone](https://github.com/clojurephant/clojurephant/milestones).
118+
- (For `final`) make sure we've released an `rc` already for this commit.
119+
- Have the `master` branch checked out
120+
- Run `./gradlew reckonTagPush -Preckon.stage=<stage>` (e.g. `./gradlew reckonTagPush -Preckon.stage=beta`)
121+
- This will run `check` on the project, create a version tag, and push that tag
122+
- The tag push will trigger GitHub Actions to run the `release` workflow, including the publish step if tests pass on all supported Java versions.
123+
- The publish will push the plugin to Clojars, and the Gradle Plugin Portal.
124+
- Go to the GitHub [releases](https://github.com/clojurephant/clojurephant/releases) and draft a new release. Use [the template](https://raw.githubusercontent.com/clojurephant/clojurephant/master/.github/RELEASE_TEMPLATE.md) for consistency. Ensure you check the _is a pre-release_ if this is a `beta` or `rc`.

‎.github/ISSUE_TEMPLATE/bug-report.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
name: Bug Report
3+
about: Something's not working as expected/documented
4+
---
5+
6+
## Expected Behavior
7+
8+
<!-- If you're reporting a bug, explain what should have happened -->
9+
10+
## Current Behavior
11+
12+
<!-- If you're reporting a bug, what happened instead of expected behavior -->
13+
14+
## Context
15+
16+
<!-- How does this bug impact your workflow? i.e. What's the value? -->
17+
<!-- Link to any relevant discussions in other issues or forums, as applicable -->
18+
19+
## Steps to reproduce
20+
21+
<!-- If reporting a bug, provide steps to recreate and ideally a reproducible sample project -->
22+
23+
## Environment
24+
25+
<!-- A build scan -- https://scans.gradle.com/get-started -- is an ideal way to provide environment info -->
26+
<!-- If a build scan isn't feasible, the output of ./gradlew --version can be used for all but the clojurephant version -->
27+
28+
- **clojurephant-tooling version:**
29+
- **clojurephant version:**
30+
- **Gradle version:**
31+
- **Java version:**
32+
- **OS version:**

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: GitHub Discussions
4+
url: https://github.com/clojurephant/clojurephant/discussions

‎.github/ISSUE_TEMPLATE/feature-request.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
name: Feature Request
3+
about: Suggest an idea for the project
4+
5+
---
6+
7+
## Desired Behavior
8+
9+
<!-- If you're suggesting a feature, how should it work? -->
10+
11+
## Context
12+
13+
<!-- How would this feature impact your workflow? i.e. What's the value? -->
14+
<!-- Link to any relevant discussions in other issues or forums, as applicable -->

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<!-- Why is this change being made? -->
2+
3+
**Related issues:**
4+
5+
## Contributor Checklist
6+
7+
- [ ] Review [Contributing Guidelines](https://github.com/clojurephant/clojurephant-tooling/blob/master/.github/CONTRIBUTING.md).
8+
- [ ] Commits contain discrete changes, messages include context about why the change was made and reference the relevant issues.
9+
- [ ] Commit messages should be prefixed with one of the following (these are used to determine the next version we release):
10+
- `patch: ` if the change added no new functionality and is backwards compatible
11+
- `minor: ` if the change added new functionality and is backwards compatible
12+
- `major: ` if the change is not backwards compatible
13+
- `chore: ` if the change doesn't affect plugin logic/behavior at all (and obviously still backwards compatible)
14+
- Any of these can optionally specify an area of the plugin they affected in parentheses (e.g. `patch(clojurescript): `)
15+
- `build`
16+
- `docs`
17+
- `clojure`
18+
- `clojurescript`
19+
- [ ] Provide functional tests.
20+
- [ ] Update documentation for user-facing changes. (under `docs/`)
21+
- [ ] Ensure all verification tasks pass locally. (`./gradlew check`)
22+
- [ ] Ensure CI builds pass on all Java versions. (watch the checks tab once the PR is opened)
23+
24+
**TIP:** If troubleshooting a CI failure, look for the build scan URL in the workflow run summary.

‎.github/RELEASE_TEMPLATE.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
<!-- User facing summary of the key changes in this release -->
2+
3+
<!--
4+
In each section below list the included changes in this release **since the last final release**.
5+
- This should be an unordered list
6+
- If no changes for the section replace use: _None_
7+
- Significant dependency updates should be listed as well
8+
9+
Breaking changes indicate:
10+
- Drop compatibility for a Java or Gradle version
11+
- Require a change to the user's build scripts
12+
- Change behavior in workflow-breaking way
13+
14+
Enhancements indicate:
15+
- Introduction of a new feature/behavior that does not meet breaking criteria above
16+
17+
Fixes indicate:
18+
- A fix to an issue that does not meet the breaking criteria above
19+
20+
Deprecations indicate:
21+
- Features that should no longer be used
22+
23+
Listed changes should include:
24+
- Issue/PR number at the start of the line
25+
- Brief summary of the change and its impact on users
26+
- In parentheses, GitHub handle of the user who provided the change (if not a core team member)
27+
28+
Example:
29+
30+
- #123 Dropped support for Gradle versions before 4.3 due to use of Provider API to lazily configure tasks.
31+
-->
32+
33+
## Breaking Changes
34+
35+
_None_
36+
37+
## Enhancements
38+
39+
_None_
40+
41+
## Fixes
42+
43+
_None_
44+
45+
## Deprecations
46+
47+
_None_
48+
49+
## Compatibility
50+
51+
Tested on the following Clojurephant versions:

‎.github/workflows/ci.yaml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: CI
2+
on:
3+
push:
4+
branches: [main]
5+
pull_request:
6+
concurrency:
7+
group: ci-${{ github.ref }}
8+
cancel-in-progress: true
9+
jobs:
10+
ci:
11+
runs-on: ubuntu-latest
12+
timeout-minutes: 10
13+
env:
14+
GRADLE_OPTS: -Dorg.gradle.java.installations.fromEnv=JAVA_HOME_8_x64,JAVA_HOME_11_x64,JAVA_HOME_17_x64
15+
steps:
16+
- name: Checkout repo
17+
uses: actions/checkout@v3
18+
with:
19+
fetch-depth: 0
20+
21+
- name: Setup Java 8
22+
uses: actions/setup-java@v3
23+
with:
24+
distribution: temurin
25+
java-version: 8
26+
- name: Setup Java 11
27+
uses: actions/setup-java@v3
28+
with:
29+
distribution: temurin
30+
java-version: 11
31+
- name: Setup Java 17
32+
uses: actions/setup-java@v3
33+
with:
34+
distribution: temurin
35+
java-version: 17
36+
37+
- name: Validate Gradle Wrapper
38+
uses: gradle/wrapper-validation-action@v1
39+
- name: Setup Gradle
40+
uses: gradle/gradle-build-action@v2
41+
- name: Gradle check
42+
run: ./gradlew check --scan

‎.github/workflows/release.yaml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: Release
2+
on:
3+
push:
4+
tags: ["*"]
5+
jobs:
6+
release:
7+
runs-on: ubuntu-latest
8+
timeout-minutes: 10
9+
steps:
10+
- name: Checkout repo
11+
uses: actions/checkout@v2
12+
with:
13+
fetch-depth: 0
14+
- name: Setup Java 11
15+
uses: actions/setup-java@v2
16+
with:
17+
distribution: zulu
18+
java-version: 11
19+
- name: Setup Java 17
20+
uses: actions/setup-java@v2
21+
with:
22+
distribution: zulu
23+
java-version: 17
24+
25+
- name: Setup Gradle
26+
uses: gradle/gradle-build-action@v2
27+
- name: Gradle publish
28+
env:
29+
CLOJARS_USER: ${{ secrets.CLOJARS_USER }}
30+
CLOJARS_TOKEN: ${{ secrets.CLOJARS_TOKEN }}
31+
run: ./gradlew publish --scan

‎.gitignore‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,34 @@
22
.gradle/
33
build/
44

5+
# IntelliJ
6+
*.iml
7+
*.iws
8+
*.ipr
9+
.idea
10+
11+
# Eclipse
12+
.settings/
13+
.project
14+
.classpath
15+
bin/
16+
17+
# VS Code
18+
.vs-code/
19+
20+
# Sublime
21+
*.sublime-workspace
22+
23+
# Other
24+
*~
25+
26+
# Java Profiling
27+
*.jfr
28+
*.hprof
29+
530
# Clojure
6-
.nrepl-port
731
.calva/
832
.clj-kondo/
9-
.vscode/
33+
.lsp/
34+
.nrepl-port
35+
*.edn

0 commit comments

Comments
 (0)