From 3a2c5d658c031a15ec725bceef0d57dbcda4c4ec Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sat, 7 Mar 2026 15:25:39 +0100 Subject: [PATCH 1/4] docs: documentation overhaul - Standardize README.md with consistent badges and structure - Add CONTRIBUTING.md with repo-specific dev setup - Add/update Antora docs structure - Remove per-repo GitHub Pages workflow - Point documentation badge to central site Signed-off-by: jimisola --- .github/workflows/publish_pages.yml | 47 --------------------- CONTRIBUTING.md | 23 +++++++++++ README.adoc | 7 ---- README.md | 63 +++++++++++++++++++++++++++++ docs/antora-playbook.yml | 1 + 5 files changed, 87 insertions(+), 54 deletions(-) delete mode 100644 .github/workflows/publish_pages.yml create mode 100644 CONTRIBUTING.md delete mode 100644 README.adoc create mode 100644 README.md diff --git a/.github/workflows/publish_pages.yml b/.github/workflows/publish_pages.yml deleted file mode 100644 index 1e63a21..0000000 --- a/.github/workflows/publish_pages.yml +++ /dev/null @@ -1,47 +0,0 @@ -name: Publish to GitHub Pages -on: - workflow_dispatch: - release: - types: [created] - push: - branches: - - main - -concurrency: - group: github-pages - cancel-in-progress: false -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages -permissions: - contents: read - pages: write - id-token: write -jobs: - build: - runs-on: ubuntu-latest - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - steps: - - name: Checkout repository - uses: actions/checkout@v6 - - name: Configure Pages - uses: actions/configure-pages@v5 - - name: Install Node.js - uses: actions/setup-node@v6 - with: - node-version: "24" - - name: Install Antora - run: npm i antora - - name: Install Asciidoctor Kroki extension - run: npm i asciidoctor asciidoctor-kroki - - name: Generate Site - run: npx antora docs/antora-playbook.yml - - name: Create site folders - run: mkdir -p docs/build/site - - name: Upload Artifacts - uses: actions/upload-pages-artifact@v4 - with: - path: docs/build/site - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3d28784 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,23 @@ +# Contributing to reqstool-java-annotations + +Thank you for your interest in contributing! + +For DCO sign-off, commit conventions, and code review process, see the organization-wide [CONTRIBUTING.md](https://github.com/reqstool/.github/blob/main/CONTRIBUTING.md). + +## Prerequisites + +- Java 21+ +- Maven 3.9+ + +## Setup + +```bash +git clone https://github.com/reqstool/reqstool-java-annotations.git +cd reqstool-java-annotations +``` + +## Build & Test + +```bash +mvn verify +``` diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 88bc31e..0000000 --- a/README.adoc +++ /dev/null @@ -1,7 +0,0 @@ - -image:https://img.shields.io/github/commit-activity/m/reqstool/reqstool-java-annotations?label=commits&style=for-the-badge["Commit Activity", link="https://github.com/reqstool/reqstool-java-annotations/pulse"] -image:https://img.shields.io/github/issues/reqstool/reqstool-java-annotations?style=for-the-badge&logo=github["GitHub Issues", link="https://github.com/reqstool/reqstool-java-annotations/issues"] -image:https://img.shields.io/badge/Java-21-brightgreen.svg?style=for-the-badge["JVM support", link="https://sdkman.io"] -image:https://img.shields.io/github/license/reqstool/reqstool-java-annotations?style=for-the-badge&logo=opensourceinitiative["License", link="https://opensource.org/license/mit/"] -image:https://img.shields.io/github/actions/workflow/status/reqstool/reqstool-java-annotations/build.yml?style=for-the-badge&logo=github["Build", link="https://github.com/reqstool/reqstool-java-annotations/actions/workflows/build.yml"] -image:https://img.shields.io/badge/Documentation-blue?style=for-the-badge&link=docs["Static Badge", link="https://reqstool.github.io/reqstool-java-annotations/reqstool-java-annotations/1.0.0/index.html"] diff --git a/README.md b/README.md new file mode 100644 index 0000000..c5f68a0 --- /dev/null +++ b/README.md @@ -0,0 +1,63 @@ +[![Commit Activity](https://img.shields.io/github/commit-activity/m/reqstool/reqstool-java-annotations?label=commits&style=for-the-badge)](https://github.com/reqstool/reqstool-java-annotations/pulse) +[![GitHub Issues](https://img.shields.io/github/issues/reqstool/reqstool-java-annotations?style=for-the-badge&logo=github)](https://github.com/reqstool/reqstool-java-annotations/issues) +[![License](https://img.shields.io/github/license/reqstool/reqstool-java-annotations?style=for-the-badge&logo=opensourceinitiative)](https://opensource.org/license/mit/) +[![Build](https://img.shields.io/github/actions/workflow/status/reqstool/reqstool-java-annotations/build.yml?style=for-the-badge&logo=github)](https://github.com/reqstool/reqstool-java-annotations/actions/workflows/build.yml) +[![Documentation](https://img.shields.io/badge/Documentation-blue?style=for-the-badge&link=docs)](https://reqstool.github.io) + +# Reqstool Java Annotations + +Java annotations for [reqstool](https://github.com/reqstool/reqstool-client) requirements traceability. + +## Overview + +Provides `@Requirements` and `@SVCs` annotations for linking Java code to requirements and software verification cases. Used together with the [Maven Plugin](https://github.com/reqstool/reqstool-java-maven-plugin) or [Gradle Plugin](https://github.com/reqstool/reqstool-java-gradle-plugin). + +## Installation + +Add the dependency to your project: + +### Maven + +```xml + + io.github.reqstool + reqstool-java-annotations + 1.0.0 + +``` + +### Gradle + +```groovy +implementation 'io.github.reqstool:reqstool-java-annotations:1.0.0' +``` + +## Usage + +```java +import io.github.reqstool.annotations.Requirements; +import io.github.reqstool.annotations.SVCs; + +@Requirements({"REQ_001", "REQ_002"}) +public class MyService { + // Implementation +} + +@Test +@SVCs("SVC_001") +public void testMyService() { + // Test +} +``` + +## Documentation + +Full documentation can be found [here](https://reqstool.github.io). + +## Contributing + +See the organization-wide [CONTRIBUTING.md](https://github.com/reqstool/.github/blob/main/CONTRIBUTING.md). + +## License + +MIT License. diff --git a/docs/antora-playbook.yml b/docs/antora-playbook.yml index 276d341..9d39e36 100644 --- a/docs/antora-playbook.yml +++ b/docs/antora-playbook.yml @@ -1,4 +1,5 @@ # yaml-language-server: $schema=https://raw.githubusercontent.com/asciidoctor/asciidoctor-intellij-plugin/main/src/main/resources/jsonSchemas/antoraPlaybookSchema.json +# For local development only. Published site: https://reqstool.github.io site: title: Reqstool Java Annotations Documentation From 3aaee89920266564e524bf0f6edbd50f7fe35ddd Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sat, 7 Mar 2026 16:42:11 +0100 Subject: [PATCH 2/4] docs: streamline nav and page structure - Separate nav items instead of single monolithic page - Merge description.adoc content into index.adoc - Add license section to index.adoc - Change nav label from All to Overview Signed-off-by: jimisola --- docs/modules/ROOT/nav.adoc | 3 +-- docs/modules/ROOT/pages/description.adoc | 6 ------ docs/modules/ROOT/pages/index.adoc | 8 ++++---- 3 files changed, 5 insertions(+), 12 deletions(-) delete mode 100644 docs/modules/ROOT/pages/description.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index be2b485..4ba6ec7 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,5 +1,4 @@ -* xref:index.adoc[All] -* xref:description.adoc[Description] +* xref:index.adoc[Overview] * xref:installation.adoc[Installation] * xref:usage.adoc[Usage] * xref:debugging.adoc[Debugging] diff --git a/docs/modules/ROOT/pages/description.adoc b/docs/modules/ROOT/pages/description.adoc deleted file mode 100644 index 3fcd85a..0000000 --- a/docs/modules/ROOT/pages/description.adoc +++ /dev/null @@ -1,6 +0,0 @@ -== Description - -This provides Java annotations and processing of annotated code. - -Enables the usage of `@Requirements` and `@SVCs` annotations and processors to collect, format and write annotations data to yaml files. - diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 89de148..ca7e937 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,9 +1,9 @@ = Reqstool Java Annotations -include::description.adoc[] +This provides Java annotations and processing of annotated code. -include::installation.adoc[] +Enables the usage of `@Requirements` and `@SVCs` annotations and processors to collect, format and write annotations data to yaml files. -include::usage.adoc[] +== License -include::debugging.adoc[] +MIT License. From a88093000693f345eb64ed47c2dbd89e66016a99 Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sat, 7 Mar 2026 18:43:11 +0100 Subject: [PATCH 3/4] docs: use lowercase reqstool consistently Signed-off-by: jimisola --- docs/modules/ROOT/pages/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index ca7e937..b583519 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,4 +1,4 @@ -= Reqstool Java Annotations += reqstool Java Annotations This provides Java annotations and processing of annotated code. From ea9fd889825e947ac89cd9828c43cffe0d5a49a8 Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sat, 7 Mar 2026 19:08:06 +0100 Subject: [PATCH 4/4] docs: add cross-component xrefs to Maven and Gradle plugins Signed-off-by: jimisola --- docs/modules/ROOT/pages/index.adoc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index b583519..3e919ab 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -4,6 +4,11 @@ This provides Java annotations and processing of annotated code. Enables the usage of `@Requirements` and `@SVCs` annotations and processors to collect, format and write annotations data to yaml files. +== Related components + +* xref:reqstool-java-maven-plugin::index.adoc[Maven Plugin] -- packages annotations into a reqstool artifact during Maven builds +* xref:reqstool-java-gradle-plugin::index.adoc[Gradle Plugin] -- packages annotations into a reqstool artifact during Gradle builds + == License MIT License.