feat: Improve overall devex for contributors to the codebase#154
Merged
Conversation
- Command surface: - add a root `Justfile` with namespaced `api`, `ui`, and `release` modules so humans and agents can use the same entrypoints from the repo root - add project-local Justfiles for `booklore-api`, `booklore-ui`, and `tools/release` so each area remains self-contained and can still be driven from inside its own directory - standardize local developer workflows around `just check`, `just test`, `just api run`, `just ui dev`, `just db-up`, and `just image-build` - Workflow integration: - update the reusable test suite workflow to install `just` and run backend and frontend CI steps through the Justfiles instead of hardcoded shell commands - update the semantic-release workflows to install `just` and invoke release tooling via `just release install`, `just release preview`, and `just release run` - keep the Docker image publication workflows on the native Docker actions while moving the project-command logic into the canonical command surface - Documentation: - split backend and frontend implementation guidance into `booklore-api/README.md`, `booklore-api/CONTRIBUTING.md`, `booklore-ui/README.md`, and `booklore-ui/CONTRIBUTING.md` - simplify the top-level `README.md` and `CONTRIBUTING.md` so they stay focused on overview, policy, and navigation while pointing to component-specific guides for deeper detail - align contributor-facing examples on the `just` interface instead of mixing ad hoc Gradle, npm, Docker, and Compose commands - Developer environment: - add `mise.toml` to pin the expected Java and Node toolchain versions for local work - switch the development Compose defaults from the old Booklore database values to Grimmory-oriented defaults - keep the command layout ready for a future API/UI split without forcing that packaging change yet
- Issue intake: - rebrand the bug and feature request forms from Booklore to Grimmory - remove the old `[Bug]` and `[Feature]` title prefixes so issue titles can stay natural - default issue intake to `needs-triage` while relying on GitHub Issue Types for the primary classification - New templates: - add a dedicated enhancement template for smaller quality-of-life and UX improvements - add a documentation template for doc fixes, missing guides, and confusing setup flows - add a performance template for runtime, UI, build, and operational performance problems - Type alignment: - map the templates onto the repo's issue-type taxonomy with `Bug`, `Feature`, `Enhancement`, `Documentation`, and `Performance` - keep the larger feature template distinct from the smaller enhancement template so incoming requests are easier to triage
- Community links: - update the issue-template support link to use the canonical Grimmory Discord invite from `README.md` - update the contributing guide to point at the same Discord server - Consistency: - remove the stale invite URL so issue intake, contributor docs, and the repository landing page all reference the same community link
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
✅ Files skipped from review due to trivial changes (2)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughThe PR introduces a repository-wide Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant CI as CI Runner (GitHub Actions)
participant Install as taiki-e/install-action
participant Just as just CLI
participant Backend as booklore-api (Gradle)
participant Frontend as booklore-ui (npm)
participant Release as tools/release (semantic-release)
CI->>Install: add `just` to PATH
CI->>Just: run `just ...` (test / release preview / release)
Just->>Backend: invoke `api::test` / `api::build`
Backend-->>Just: test/build results
Just->>Frontend: invoke `ui::test` / `ui::build`
Frontend-->>Just: test/build results
alt release job
Just->>Release: run `release preview` / `release run`
Release-->>Just: semantic-release output
end
Just-->>CI: exit code / logs
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (2)
.github/ISSUE_TEMPLATE/bug_report.yml (1)
3-3: Confirm that your issue triage process is prepared for manual categorization.All issue templates now consistently use
["needs-triage"], which means issues won't be automatically categorized by type. This requires maintainers to manually label issues during triage. No existing workflow automations depend on the "bug" label, so there are no automation conflicts. Ensure your team has the capacity to triage and properly categorize incoming issues.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/ISSUE_TEMPLATE/bug_report.yml at line 3, The issue template currently sets labels to ["needs-triage"], which disables automatic categorization; confirm and update the triage process by either restoring an automatic "bug" label or adding explicit triage guidance in the template (change the labels array or add a short checklist field) and ensure the team has an assigned rotation or workflow to manually apply final labels for functions that process new issues; update the .github ISSUE_TEMPLATE entry referencing the labels array value ["needs-triage"] and/or add a visible triage instruction block so maintainers know how to categorize incoming issues.dev.docker-compose.yml (1)
52-54: Node version mismatch withmise.toml.The UI service uses
node:22-alpinewhilemise.tomlpins Node 24 for local development. Consider aligning these versions for consistency between containerized and local development environments.♻️ Suggested alignment
ui: - image: node:22-alpine + image: node:24-alpine🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@dev.docker-compose.yml` around lines 52 - 54, The docker-compose UI service is using image node:22-alpine which conflicts with mise.toml pinning Node 24; update the ui service image reference (the "ui" service's image value) to match the pinned Node version (e.g., change node:22-alpine to node:24-alpine) or, alternatively, update mise.toml if you want to standardize on Node 22—ensure the ui service image and mise.toml Node pin are the same to keep local and container dev environments consistent.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/ISSUE_TEMPLATE/bug_report.yml:
- Line 64: Replace the static placeholder string "Grimmory Version: v2.3.0" with
the current application version "v0.38.2" (as declared in
deploy/helm/grimmory/Chart.yaml) so the bug report template shows the real
version; locate the line containing the "Grimmory Version: v2.3.0" placeholder
and update it to "Grimmory Version: v0.38.2".
In `@booklore-api/README.md`:
- Around line 7-12: Update CONTRIBUTING.md to make it the single source of truth
for platform/component versions: change the Spring Boot entry to match
build.gradle's declared 4.0.3, and update Angular and PrimeNG to match
package.json (Angular 21.2.4 and PrimeNG 21.1.1); then scan
booklore-api/README.md and booklore-ui/README.md for any conflicting version
mentions (Spring Boot, Java, Angular, PrimeNG) and align or remove redundant
entries so all READMEs and CONTRIBUTING.md consistently reflect the versions
declared in build.gradle and package.json.
In `@CONTRIBUTING.md`:
- Around line 381-387: The TOC still links to the old backend/frontend anchors;
update the Table of Contents so it points to the renamed section "Component
Conventions" (use the `#component-conventions` anchor) and either replace or
remove the stale "#backend-rules" and "#frontend-rules" links, making sure the
entries for booklore-api/CONTRIBUTING.md and booklore-ui/CONTRIBUTING.md are
correctly linked or nested under the Component Conventions entry.
In `@Justfile`:
- Around line 73-84: Remove the non-portable "--network host" from the image-run
recipe and run the container using the default bridge network so the "-p
6060:6060" port mapping works across macOS/Windows; to preserve host
reachability where needed, add an explicit host entry (e.g., via
"--add-host=host.docker.internal:host-gateway" or using host.docker.internal) so
services inside the container can reach the host. Update the image-run recipe
that defines local_container_name, tag, and the SPRING_DATASOURCE_* envs to
remove "--network host" and add the cross-platform host mapping option while
keeping the existing "-p 6060:6060" and volume mounts.
---
Nitpick comments:
In @.github/ISSUE_TEMPLATE/bug_report.yml:
- Line 3: The issue template currently sets labels to ["needs-triage"], which
disables automatic categorization; confirm and update the triage process by
either restoring an automatic "bug" label or adding explicit triage guidance in
the template (change the labels array or add a short checklist field) and ensure
the team has an assigned rotation or workflow to manually apply final labels for
functions that process new issues; update the .github ISSUE_TEMPLATE entry
referencing the labels array value ["needs-triage"] and/or add a visible triage
instruction block so maintainers know how to categorize incoming issues.
In `@dev.docker-compose.yml`:
- Around line 52-54: The docker-compose UI service is using image node:22-alpine
which conflicts with mise.toml pinning Node 24; update the ui service image
reference (the "ui" service's image value) to match the pinned Node version
(e.g., change node:22-alpine to node:24-alpine) or, alternatively, update
mise.toml if you want to standardize on Node 22—ensure the ui service image and
mise.toml Node pin are the same to keep local and container dev environments
consistent.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: ec275c41-7143-40ab-9794-17345681c472
📒 Files selected for processing (21)
.github/ISSUE_TEMPLATE/bug_report.yml.github/ISSUE_TEMPLATE/config.yml.github/ISSUE_TEMPLATE/documentation.yml.github/ISSUE_TEMPLATE/enhancement.yml.github/ISSUE_TEMPLATE/feature_request.yml.github/ISSUE_TEMPLATE/performance.yml.github/workflows/release-main.yml.github/workflows/release-preview.yml.github/workflows/test-suite.ymlCONTRIBUTING.mdJustfileREADME.mdbooklore-api/CONTRIBUTING.mdbooklore-api/Justfilebooklore-api/README.mdbooklore-ui/CONTRIBUTING.mdbooklore-ui/Justfilebooklore-ui/README.mddev.docker-compose.ymlmise.tomltools/release/Justfile
| description: Help us understand your environment | ||
| placeholder: | | ||
| - Booklore Version: v1.1.0 | ||
| - Grimmory Version: v2.3.0 |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Check the latest semantic version tag
git tag --list 'v*' --sort=-v:refname | head -5Repository: grimmory-tools/grimmory
Length of output: 49
🏁 Script executed:
#!/bin/bash
# Check the actual file content and look for version information
echo "=== Content of bug_report.yml around line 64 ==="
cat -n .github/ISSUE_TEMPLATE/bug_report.yml | sed -n '55,75p'
echo -e "\n=== Check for any git tags (all patterns) ==="
git tag --list | head -20
echo -e "\n=== Look for version info in package files ==="
fd -e package.json -e setup.py -e pyproject.toml -e version.py | head -10Repository: grimmory-tools/grimmory
Length of output: 969
🏁 Script executed:
#!/bin/bash
# Search for version references in the repository
echo "=== Search for version mentions in README ==="
fd README | xargs -I {} cat {} 2>/dev/null | grep -i version | head -10
echo -e "\n=== Search for version in all Python/JS files ==="
rg "version\s*[=:].*[vV]" --max-count=10 -i
echo -e "\n=== Check for version in __init__.py or setup files ==="
fd -e __init__.py | xargs -I {} cat {} 2>/dev/null | grep -i version | head -5
echo -e "\n=== List all files in root and src directories ==="
ls -la | head -20
fd --max-depth 2 -type f | head -30Repository: grimmory-tools/grimmory
Length of output: 50567
Use the actual application version in the placeholder.
The version placeholder shows v2.3.0, but the actual application version in the codebase is v0.38.2 (from deploy/helm/grimmory/Chart.yaml). Update the placeholder to v0.38.2 to reflect the current version and avoid confusing users reporting bugs.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.github/ISSUE_TEMPLATE/bug_report.yml at line 64, Replace the static
placeholder string "Grimmory Version: v2.3.0" with the current application
version "v0.38.2" (as declared in deploy/helm/grimmory/Chart.yaml) so the bug
report template shows the real version; locate the line containing the "Grimmory
Version: v2.3.0" placeholder and update it to "Grimmory Version: v0.38.2".
Comment on lines
+7
to
+12
| - Java 25 | ||
| - Spring Boot 4 | ||
| - Gradle Wrapper | ||
| - Spring Data JPA + Flyway | ||
| - MariaDB in production, H2 for selected tests | ||
| - JUnit 5, Mockito, AssertJ, JaCoCo |
Contributor
There was a problem hiding this comment.
❓ Verification inconclusive
Script executed:
#!/bin/bash
# Verify documented stack versions against declared project config.
echo "== Docs version mentions =="
rg -n "Angular [0-9]+|PrimeNG|Spring Boot|Java [0-9]+" CONTRIBUTING.md booklore-api/README.md booklore-ui/README.md
echo
echo "== Backend declarations =="
fd -a "build.gradle|build.gradle.kts|gradle.properties" | xargs -I{} rg -n "spring-boot|org.springframework.boot|java|toolchain|sourceCompatibility" "{}"
echo
echo "== Frontend declarations =="
fd -a "package.json" | xargs -I{} rg -n "\"@angular/core\"|\"primeng\"|\"typescript\"" "{}"
echo
echo "== Toolchain pins =="
fd -a "mise.toml" | xargs -I{} cat "{}"Repository: grimmory-tools/grimmory
Repository: grimmory-tools/grimmory
Exit code: 0
stdout:
== Docs version mentions ==
booklore-ui/README.md:7:- Angular 21
booklore-ui/README.md:9:- PrimeNG + PrimeIcons
booklore-api/README.md:3:The `booklore-api` project is the Spring Boot backend for Grimmory. It owns the HTTP API, database migrations, background processing, authentication, and the packaged runtime jar that the production container runs.
booklore-api/README.md:7:- Java 25
booklore-api/README.md:8:- Spring Boot 4
CONTRIBUTING.md:11:- **Frontend:** Angular 20, TypeScript, PrimeNG 19
CONTRIBUTING.md:12:- **Backend:** Java 25, Spring Boot 3.5
CONTRIBUTING.md:92:├── booklore-ui/ # Angular frontend (TypeScript, PrimeNG)
CONTRIBUTING.md:93:├── booklore-api/ # Spring Boot backend (Java 25, Gradle)
CONTRIBUTING.md:237:To verify your changes in an environment identical to production, build and run the full Docker image locally. The multi-stage `Dockerfile` in the project root compiles both the Angular frontend and the Spring Boot backend, so you don't need any local toolchain beyond Docker.
== Backend declarations ==
2: id 'java'
3: id 'org.springframework.boot' version '4.0.3'
17:java {
18: toolchain {
36: implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
37: implementation 'org.springframework.boot:spring-boot-starter-web'
38: implementation 'org.springframework.boot:spring-boot-starter-validation'
39: implementation 'org.springframework.boot:spring-boot-starter-websocket'
40: implementation 'org.springframework.boot:spring-boot-starter-actuator'
41: implementation 'org.springframework.boot:spring-boot-configuration-processor'
42: implementation 'org.springframework.boot:spring-boot-starter-security'
43: implementation 'org.springframework.boot:spring-boot-starter-mail'
44: implementation 'org.springframework.boot:spring-boot-starter-oauth2-client'
50: implementation 'org.mariadb.jdbc:mariadb-java-client:3.5.7'
51: implementation 'org.springframework.boot:spring-boot-starter-flyway'
117: implementation 'org.springframework.boot:spring-boot-starter-cache'
121: testImplementation 'org.springframework.boot:spring-boot-starter-test'
122: testImplementation 'org.springframework.boot:spring-boot-test-autoconfigure'
== Frontend declarations ==
19: "@angular/core": "^21.2.4",
44: "primeng": "^21.1.1",
65: "typescript": "~5.9.3",
== Toolchain pins ==
min_version = "2024.9.5"
[tools]
java = "temurin-25"
node = "24"
[settings]
experimental = true
[hooks]
postinstall = "npx corepack enable"
[env]
_.path = ["{{config_root}}/node_modules/.bin"]
Synchronize documentation versions across contributor and component READMEs.
Version drift extends beyond Spring Boot: booklore-api/README.md documents Spring Boot 4, CONTRIBUTING.md documents Spring Boot 3.5 (both outdated compared to the declared 4.0.3 in build.gradle). Additionally, CONTRIBUTING.md lists Angular 20 and PrimeNG 19 while actual package.json versions are 21.2.4 and 21.1.1 respectively, and booklore-ui/README.md correctly lists Angular 21. Update CONTRIBUTING.md as the central source of truth to match declared versions in build.gradle and package.json.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@booklore-api/README.md` around lines 7 - 12, Update CONTRIBUTING.md to make
it the single source of truth for platform/component versions: change the Spring
Boot entry to match build.gradle's declared 4.0.3, and update Angular and
PrimeNG to match package.json (Angular 21.2.4 and PrimeNG 21.1.1); then scan
booklore-api/README.md and booklore-ui/README.md for any conflicting version
mentions (Spring Boot, Java, Angular, PrimeNG) and align or remove redundant
entries so all READMEs and CONTRIBUTING.md consistently reflect the versions
declared in build.gradle and package.json.
Comment on lines
+381
to
387
| ## Component Conventions | ||
|
|
||
| ## Frontend Conventions | ||
| Detailed coding conventions now live with each project: | ||
|
|
||
| - Follow the [Angular style guide](https://angular.dev/style-guide). | ||
| - All components are standalone. No NgModules. | ||
| - Use `inject()` for dependency injection. No constructor injection. | ||
| - PrimeNG for UI components. SCSS for styling. Transloco for i18n. | ||
| - Testing with Vitest (not Karma/Jasmine). | ||
| - All UI features must be responsive (desktop + mobile). | ||
| - Backend rules: [booklore-api/CONTRIBUTING.md](booklore-api/CONTRIBUTING.md) | ||
| - Frontend rules: [booklore-ui/CONTRIBUTING.md](booklore-ui/CONTRIBUTING.md) | ||
|
|
Contributor
There was a problem hiding this comment.
Update the Table of Contents to match the renamed section.
Line 381 renamed the section to Component Conventions, but the TOC still points to backend/frontend convention anchors, which breaks in-page navigation.
🛠️ Suggested TOC fix
-- [Backend Conventions](`#backend-conventions`)
-- [Frontend Conventions](`#frontend-conventions`)
+- [Component Conventions](`#component-conventions`)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CONTRIBUTING.md` around lines 381 - 387, The TOC still links to the old
backend/frontend anchors; update the Table of Contents so it points to the
renamed section "Component Conventions" (use the `#component-conventions` anchor)
and either replace or remove the stale "#backend-rules" and "#frontend-rules"
links, making sure the entries for booklore-api/CONTRIBUTING.md and
booklore-ui/CONTRIBUTING.md are correctly linked or nested under the Component
Conventions entry.
Comment on lines
+73
to
+84
| image-run tag=local_image_tag db_url=local_db_url db_user=local_db_user db_password=local_db_password: | ||
| docker run --rm -it \ | ||
| --name "{{ local_container_name }}" \ | ||
| --network host \ | ||
| -e "SPRING_DATASOURCE_URL={{ db_url }}" \ | ||
| -e "SPRING_DATASOURCE_USERNAME={{ db_user }}" \ | ||
| -e "SPRING_DATASOURCE_PASSWORD={{ db_password }}" \ | ||
| -v ./shared/data:/app/data \ | ||
| -v ./shared/books:/books \ | ||
| -v ./shared/bookdrop:/bookdrop \ | ||
| -p 6060:6060 \ | ||
| "{{ tag }}" |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
For Docker Engine / Docker Desktop current docs: is docker run --network hostsupported on macOS and Windows, and are-p published ports ignored when host networking is enabled?
💡 Result:
- macOS & Windows:
docker run --network hostis not supported in Docker Engine on macOS/Windows, but it is supported in Docker Desktop 4.34+ as an opt-in feature (Settings → Resources → Network → “Enable host networking”). It works for Linux containers; it does not work for Windows containers. [1] - Published ports with host networking: When
--network hostis used, port-mapping does not apply;-p/--publishand-P/--publish-allare ignored (Docker emits a warning that published ports are discarded). [1]
Sources:
[1] Docker Docs — Host network driver (--network host) https://docs.docker.com/engine/network/drivers/host/
--network host is not portable across platforms and makes port mapping ineffective.
Line 76 uses --network host, which is unsupported on Docker Engine for macOS and Windows (works only on Linux). Even in Docker Desktop 4.34+ where this is available as an opt-in feature, line 83's -p 6060:6060 port mapping is discarded and ignored. This creates confusion and breaks the setup for non-Linux users.
Use host.docker.internal for cross-platform compatibility:
🌐 Portable alternative
-local_db_url := 'jdbc:mariadb://localhost:3366/grimmory?createDatabaseIfNotExist=true'
+local_db_url := 'jdbc:mariadb://host.docker.internal:3366/grimmory?createDatabaseIfNotExist=true'
image-run tag=local_image_tag db_url=local_db_url db_user=local_db_user db_password=local_db_password:
docker run --rm -it \
--name "{{ local_container_name }}" \
- --network host \
+ --add-host=host.docker.internal:host-gateway \
-e "SPRING_DATASOURCE_URL={{ db_url }}" \
-e "SPRING_DATASOURCE_USERNAME={{ db_user }}" \
-e "SPRING_DATASOURCE_PASSWORD={{ db_password }}" \
-v ./shared/data:/app/data \
-v ./shared/books:/books \
-v ./shared/bookdrop:/bookdrop \
-p 6060:6060 \
"{{ tag }}"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@Justfile` around lines 73 - 84, Remove the non-portable "--network host" from
the image-run recipe and run the container using the default bridge network so
the "-p 6060:6060" port mapping works across macOS/Windows; to preserve host
reachability where needed, add an explicit host entry (e.g., via
"--add-host=host.docker.internal:host-gateway" or using host.docker.internal) so
services inside the container can reach the host. Update the image-run recipe
that defines local_container_name, tag, and the SPRING_DATASOURCE_* envs to
remove "--network host" and add the cross-platform host mapping option while
keeping the existing "-p 6060:6060" and volume mounts.
- Community links: - replace the old Discord invite code with the new `9YJ7HB4n8T` invite in the repository README - update the contributor guide to point at the same server - align the issue-template support link with the same canonical invite - Consistency: - keep the public docs and issue intake flow on a single Discord destination so users and contributors land in the right community space
This was referenced Apr 16, 2026
7 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Linked Issue: Fixes #
Changes
Summary by CodeRabbit