Skip to content

Commit 2ab5c64

Browse files
janderssonsejanderssonse
authored
chore!: clean up pom, add dev docs
Signed-off-by: Josef Andersson <josef.andersson@digg.se>
1 parent c8f8540 commit 2ab5c64

File tree

3 files changed

+255
-28
lines changed

3 files changed

+255
-28
lines changed

‎.github/workflows/openssf-scorecard.yml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,10 @@
66
name: OpenSSF Scorecard Analysis
77
on:
88
schedule:
9-
# Saturdays at 01:40 UTC
10-
- cron: "40 1 * * 6"
11-
# Wednesdays at 01:40 UTC
12-
- cron: "40 1 * * 3"
9+
# Saturdays at 01:50 UTC
10+
- cron: "50 1 * * 6"
11+
# Wednesdays at 01:50 UTC
12+
- cron: "50 1 * * 3"
1313
workflow_dispatch:
1414

1515
permissions:

‎docs/DEVELOPMENT.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# Development Guide
2+
3+
This guide outlines core essentials for developing in this project.
4+
5+
## Table of Contents
6+
- [Setup and Configuration](#setup-and-configuration)
7+
- [IDE Setup](#ide-setup)
8+
- [Consuming SNAPSHOTS](#consuming-snapshots-from-maven-central)
9+
- [Development Workflow](#development-workflow)
10+
- [Testing and Verification](#testing-format-and-lint)
11+
- [Documentation](#documentation)
12+
- [Pull Request Process](#pull-request-workflow)
13+
- [Release Process](#the-release-workflow)
14+
- [CI Release](#ci-release-process)
15+
- [Local Release](#local-release-process)
16+
- [Troubleshooting](#troubleshooting)
17+
18+
## Setup and Configuration
19+
20+
### IDE Setup
21+
22+
#### VSCode
23+
24+
1. Install [Checkstyle For Java](https://marketplace.visualstudio.com/items?itemName=shengchen.vscode-checkstyle)
25+
2. Open workspace settings - settings.json (for example with Ctrl+Shift+P → Preferences: Workspace Settings (JSON)) and add:
26+
```json
27+
"[java]": {
28+
"editor.defaultFormatter": "redhat.java",
29+
},
30+
"java.format.settings.url": "development/format/eclipse-java-google-style.xml",
31+
"java.format.settings.profile": "GoogleStyle",
32+
"editor.formatOnSave": true,
33+
"java.checkstyle.configuration": "development/lint/google_checks.xml",
34+
"java.checkstyle.version": "1x.xx.x"
35+
```
36+
37+
#### IntelliJ
38+
39+
1. **Code Style**
40+
- Settings → `Editor → Code Style → Java`
41+
- Click gear → `Import Scheme → Eclipse XML Profile`
42+
- Select `development/format/eclipse-java-google-style.xml`
43+
44+
2. **Checkstyle**
45+
- Install "CheckStyle-IDEA" plugin
46+
- Settings → `Tools → Checkstyle`
47+
- Click the built-in Google Style Check
48+
49+
### Consuming SNAPSHOTS from Maven Central
50+
51+
Configure your pom.xml with:
52+
53+
```xml
54+
<repositories>
55+
<repository>
56+
<name>Central Portal Snapshots</name>
57+
<id>central-portal-snapshots</id>
58+
<url>https://central.sonatype.com/repository/maven-snapshots/</url>
59+
<releases>
60+
<enabled>false</enabled>
61+
</releases>
62+
<snapshots>
63+
<enabled>true</enabled>
64+
</snapshots>
65+
</repository>
66+
</repositories>
67+
```
68+
69+
## Development Workflow
70+
71+
### Testing, Format and Lint
72+
73+
Run Maven verification:
74+
```shell
75+
mvn clean verify
76+
```
77+
78+
### Documentation
79+
80+
Generate Javadocs:
81+
```shell
82+
mvn javadoc:javadoc
83+
```
84+
85+
View documentation in your browser:
86+
```shell
87+
<browser> target/reports/apidocs/index.html
88+
```
89+
90+
### Pull Request Workflow
91+
92+
When submitting a PR, CI will automatically run several checks. To avoid surprises, run these checks locally first.
93+
94+
#### Prerequisites
95+
- [Podman](https://podman.io/)
96+
97+
#### Running Code Quality Checks Locally
98+
99+
1. Run the quality check script:
100+
```shell
101+
./development/code_quality.sh
102+
```
103+
2. Fix any identified issues
104+
3. Update your PR with fixes
105+
4. Verify CI passes in the updated PR
106+
107+
#### Quality Check Details
108+
109+
- **Linting with megalinter**: BASH, Markdown, YAML, GitHub Actions, security scanning
110+
- **License Compliance**: REUSE tool ensures proper copyright information
111+
- **Commit Structure**: Conform checks commit messages for changelog generation
112+
- **Dependency Analysis**: Scans for vulnerabilities, outdated packages, and license issues
113+
- **OpenSSF Scorecard**: Validates security best practices
114+
115+
#### Handling Failed Checks
116+
117+
If any checks fail in the CI pipeline:
118+
119+
1. Review the CI error logs
120+
2. Run checks locally to reproduce the issues
121+
3. Make necessary fixes in your local environment
122+
4. Update your Pull Request
123+
5. Verify all checks pass in the updated PR
124+
125+
## The Release Workflow
126+
127+
Releases to Maven Central can be done via CI or locally.
128+
129+
### Prerequisites
130+
131+
1. **For CI releases**:
132+
- Push access to the repository (ability to push tags)
133+
- For production releases: Your GitHub username in AUTHORIZED_RELEASE_DEVELOPERS list
134+
- For SNAPSHOT releases: Any contributor with tag push access
135+
136+
2. **For local releases only**:
137+
- Valid GPG key pair for signing artifacts
138+
- GPG key uploaded to key servers (e.g., `keyserver.ubuntu.com`)
139+
- Maven Central credentials in settings.xml
140+
141+
### CI Release Process
142+
143+
1. **For SNAPSHOT releases**:
144+
```shell
145+
# Tag with -SNAPSHOT suffix (use -f to force if tag already exists)
146+
git tag -sf v0.0.1-SNAPSHOT -m 'v0.0.1-SNAPSHOT'
147+
# Push the tag to trigger the CI workflow (use -f to force update on remote)
148+
git push -f origin tag v0.0.1-SNAPSHOT
149+
```
150+
151+
> **NOTE**: Always use the same SNAPSHOT tag version until ready for a production release.
152+
153+
2. **For Production releases**:
154+
```shell
155+
# Tag with the desired version (no SNAPSHOT suffix)
156+
git tag -s v1.0.0 -m 'v1.0.0'
157+
# Push the tag to trigger the CI workflow
158+
git push origin tag v1.0.0
159+
```
160+
161+
> **NOTE**: The tag version will be used in the POM file.
162+
163+
3. **Monitor the workflow** in GitHub Actions to ensure successful completion.
164+
165+
> **NOTE**: If the workflow fails due to authorization issues, contact the repository administrator to add your GitHub username to the AUTHORIZED_RELEASE_DEVELOPERS list.
166+
167+
### Local Release Process
168+
169+
1. **Configure settings.xml**:
170+
- Ensure `.mvn/settings.xml` contains your Maven Central username and token
171+
- Verify credentials are in the correct server section with the proper server ID
172+
- Make sure your GPG key is available in your environment
173+
174+
2. **Run the deploy command**:
175+
```shell
176+
mvn deploy --settings .mvn/settings.xml -Pcentral-release
177+
```
178+
179+
3. **Verify the release** in your Sonatype account or Maven Central.
180+
181+
### Troubleshooting
182+
183+
- For CI failures: Check GitHub Actions logs for detailed error information
184+
- For authorization issues: Verify your GitHub username is in AUTHORIZED_RELEASE_DEVELOPERS
185+
- For GPG problems: Ensure your key is correctly configured in your environment

‎pom.xml‎

Lines changed: 66 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -12,42 +12,57 @@ SPDX-License-Identifier: EUPL-1.2
1212
<modelVersion>4.0.0</modelVersion>
1313

1414
<groupId>se.digg.crypto</groupId>
15-
<artifactId>hash-to-curve</artifactId>
15+
<artifactId>hash2curve</artifactId>
1616
<version>0.0.1-SNAPSHOT</version>
1717

18-
<name>DIGG Crypto :: Hash2Curve</name>
18+
<name>Hash2Curve Java Library</name>
1919
<description>Implementation of Hash2Curve and Hash2Scalar in accordance with RFC 9380</description>
20+
<url>https://github.com/diggsweden/hash2curve-lib-java</url>
2021

2122
<organization>
2223
<name>Myndigheten för Digital Förvaltning</name>
2324
<url>https://www.digg.se</url>
2425
</organization>
2526

26-
<developers>
27-
<developer>
28-
<name>Stefan Santesson</name>
29-
<email>stefan@aaa-sec.com</email>
30-
</developer>
31-
</developers>
27+
<licenses>
28+
<license>
29+
<name>European Union Public License 1.2</name>
30+
<url>https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12</url>
31+
<distribution>repo</distribution>
32+
</license>
33+
</licenses>
34+
35+
<scm>
36+
<connection>scm:git:https://github.com/diggsweden/hash2curve-lib-java.git</connection>
37+
<developerConnection>scm:git:git@github.com:diggsweden/hash2curve-lib-java.git</developerConnection>
38+
<url>https://github.com/diggsweden/hash2curve-lib-java</url>
39+
</scm>
40+
3241

3342
<properties>
34-
<java.version>21</java.version>
43+
<!-- Project settings -->
3544
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
3645
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
37-
38-
<slf4j.version>2.0.17</slf4j.version>
39-
<bouncycastle.version>1.82</bouncycastle.version>
40-
46+
<java.version>21</java.version>
4147
<maven.compiler.source>${java.version}</maven.compiler.source>
4248
<maven.compiler.target>${java.version}</maven.compiler.target>
4349
<maven.compiler.release>${java.version}</maven.compiler.release>
44-
<maven-deploy-plugin.version>3.1.3</maven-deploy-plugin.version>
45-
<maven.source.plugin.version>3.3.1</maven.source.plugin.version>
50+
51+
<!-- Dependency versions -->
52+
<bouncycastle.version>1.82</bouncycastle.version>
53+
<jackson.version>2.20.0</jackson.version>
54+
<junit.version>5.14.0</junit.version>
55+
<lombok.version>1.18.42</lombok.version>
56+
<slf4j.version>2.0.17</slf4j.version>
57+
58+
<!-- Maven plugin versions -->
59+
<central-publishing.version>0.9.0</central-publishing.version>
4660
<maven.compiler.plugin.version>3.14.1</maven.compiler.plugin.version>
47-
<!-- Plugin versions -->
48-
<maven.javadoc.plugin.version>3.12.0</maven.javadoc.plugin.version>
61+
<maven-deploy-plugin.version>3.1.3</maven-deploy-plugin.version>
62+
<maven-enforcer-plugin.version>3.6.2</maven-enforcer-plugin.version>
4963
<maven.gpg.plugin.version>3.2.8</maven.gpg.plugin.version>
50-
64+
<maven.javadoc.plugin.version>3.12.0</maven.javadoc.plugin.version>
65+
<maven.source.plugin.version>3.3.1</maven.source.plugin.version>
5166
</properties>
5267

5368
<dependencyManagement>
@@ -81,7 +96,7 @@ SPDX-License-Identifier: EUPL-1.2
8196
<dependency>
8297
<groupId>org.projectlombok</groupId>
8398
<artifactId>lombok</artifactId>
84-
<version>1.18.42</version>
99+
<version>${lombok.version}</version>
85100
</dependency>
86101

87102
<dependency>
@@ -93,7 +108,7 @@ SPDX-License-Identifier: EUPL-1.2
93108
<groupId>org.junit.jupiter</groupId>
94109
<artifactId>junit-jupiter</artifactId>
95110
<scope>test</scope>
96-
<version>5.14.0</version>
111+
<version>${junit.version}</version>
97112
</dependency>
98113

99114
<dependency>
@@ -104,26 +119,53 @@ SPDX-License-Identifier: EUPL-1.2
104119
<dependency>
105120
<groupId>org.slf4j</groupId>
106121
<artifactId>slf4j-simple</artifactId>
107-
<version>2.0.17</version>
122+
<version>${slf4j.version}</version>
108123
<scope>test</scope>
109124
</dependency>
110125

111126
<dependency>
112127
<groupId>com.fasterxml.jackson.core</groupId>
113128
<artifactId>jackson-databind</artifactId>
114-
<version>2.20.0</version>
129+
<version>${jackson.version}</version>
115130
<scope>test</scope>
116131
</dependency>
117132

118133
</dependencies>
119134

120135
<build>
121136
<plugins>
137+
<!-- Enforcer -->
138+
<plugin>
139+
<groupId>org.apache.maven.plugins</groupId>
140+
<artifactId>maven-enforcer-plugin</artifactId>
141+
<version>${maven-enforcer-plugin.version}</version>
142+
<executions>
143+
<execution>
144+
<id>enforce-rules</id>
145+
<goals>
146+
<goal>enforce</goal>
147+
</goals>
148+
<configuration>
149+
<rules>
150+
<requireMavenVersion>
151+
<version>[3.8.0,)</version>
152+
</requireMavenVersion>
153+
<requireJavaVersion>
154+
<version>[21,)</version>
155+
</requireJavaVersion>
156+
<dependencyConvergence/>
157+
<requireUpperBoundDeps/>
158+
</rules>
159+
</configuration>
160+
</execution>
161+
</executions>
162+
</plugin>
163+
122164
<!-- Deployment -->
123165
<plugin>
124166
<groupId>org.sonatype.central</groupId>
125167
<artifactId>central-publishing-maven-plugin</artifactId>
126-
<version>0.9.0</version>
168+
<version>${central-publishing.version}</version>
127169
<extensions>true</extensions>
128170
<configuration>
129171
<checksums>all</checksums>
@@ -174,7 +216,7 @@ SPDX-License-Identifier: EUPL-1.2
174216
<version>${maven.javadoc.plugin.version}</version>
175217
<configuration>
176218
<source>${java.version}</source>
177-
<bottom>hash-to-curve for Java documentation, generated in {currentYear}.</bottom>
219+
<bottom>Hash2Curve Java Library documentation, generated in {currentYear}.</bottom>
178220
</configuration>
179221
<executions>
180222
<execution>

0 commit comments

Comments
 (0)