Skip to content

Commit 937cb36

Browse files
toddbaerttoddbaert
authored
chore: Add contributing guide (#117)
* chore: Add contributing guide
1 parent 15e8e10 commit 937cb36

File tree

2 files changed

+103
-78
lines changed

2 files changed

+103
-78
lines changed

‎CONTRIBUTING.md

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Contributing
2+
3+
## System Requirements
4+
5+
Java 18 is recommended for the tooling, plugins, etc. Maven 3.8+ is recommended.
6+
7+
## Compilation target(s)
8+
9+
As in the Java-SDK, we target Java 8. The parent POM configures this automatically.
10+
11+
## Adding a module
12+
13+
1. Create a [standard directory structure](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html) in the appropriate folder (`hooks/`, `providers/`).
14+
1. Create a new `pom.xml` in the root of your new module. It must inherit from the parent POM, which implements the javadoc, testing, publishing, and other boilerplate. Be sure to add `<!--x-release-please-version -->` on the line specifying the module version, so our release tooling can update it (see sample pom below).
15+
1. Add the new package to `release-please-config.json`.
16+
1. Add the new module to the `<modules>...</modules>` section in the parent `pom.xml`.
17+
1. Add a `version.txt` file with a version matching that in your new `pom.xml`, e.g. `0.0.1`.
18+
1. If you care to release a pre 1.0.0 version, add the same version above to `.release-please-manifest.json`. Failing to do this will release a `1.0.0` initial release.
19+
20+
Sample pom.xml:
21+
22+
```xml
23+
<?xml version="1.0" encoding="UTF-8"?>
24+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
25+
<modelVersion>4.0.0</modelVersion>
26+
<modelVersion>4.0.0</modelVersion>
27+
<parent>
28+
<groupId>dev.openfeature.contrib</groupId>
29+
<artifactId>parent</artifactId>
30+
<version><!-- current parent pom version --></version>
31+
<relativePath>../../pom.xml</relativePath>
32+
</parent>
33+
<!-- The group id MUST start with dev.openfeature, or publishing will fail. OpenFeature has verified ownership of this (reversed) domain. -->
34+
<groupId>dev.openfeature.contrib.${providers | hooks | etc}</groupId>
35+
<artifactId>module</artifactId>
36+
<version>0.0.1</version> <!--x-release-please-version -->
37+
38+
<name>module</name>
39+
<description>Your module description</description>
40+
<url>https://openfeature.dev</url>
41+
42+
<developers>
43+
<developer>
44+
<id>Your GitHub ID</id>
45+
<name>Your Name</name>
46+
<organization>OpenFeature</organization>
47+
<url>https://openfeature.dev/</url>
48+
</developer>
49+
</developers>
50+
51+
<dependencies>
52+
<!-- dependencies your module needs (in addition to those inherited from parent) -->
53+
</dependencies>
54+
55+
<build>
56+
<plugins>
57+
<!-- plugins your module needs (in addition to those inherited from parent) -->
58+
</plugins>
59+
</build>
60+
61+
</project>
62+
```
63+
64+
## Documentation
65+
66+
Any published modules must have documentation in their root directory, explaining the basic purpose of the module as well as installation and usage instructions.
67+
Instructions for how to develop a module should also be included (required system dependencies, instructions for testing locally, etc).
68+
69+
## Testing
70+
71+
Any published modules must have reasonable test coverage.
72+
The parent POM adds basic testing support for you.
73+
74+
Use `mvn clean test` to test the entire project.
75+
Use `mvn --projects {MODULE PATH} clean test` to test just a single module.
76+
77+
Use `mvn clean verify` to test/audit/lint the entire project.
78+
Use `mvn --projects {MODULE PATH} clean verify` to test/audit/lint just a single module.
79+
80+
## Versioning and releasing
81+
82+
As described in the [README](./README.md), this project uses release-please, and semantic versioning.
83+
Breaking changes should be identified by using a semantic PR title.
84+
Keep in mind, one version of the Java-SDK is used for all modules.
85+
86+
### VS Code config
87+
88+
To use vscode, install the standard [Java language support extension by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java).
89+
90+
The following vscode settings are recommended (create a workspace settings file at .vscode/settings.json):
91+
92+
```json
93+
{
94+
"java.configuration.updateBuildConfiguration": "interactive",
95+
"java.autobuild.enabled": false,
96+
"java.checkstyle.configuration": "${workspaceFolder}/checkstyle.xml",
97+
"java.checkstyle.version": "10.3.2",
98+
"java.format.settings.url": "${workspaceFolder}/eclipse-java-google-style.xml",
99+
"java.format.enabled": false
100+
}
101+
```

‎README.md

Lines changed: 2 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -14,85 +14,9 @@ The project includes:
1414

1515
This repo uses _Release Please_ to release packages. Release Please sets up a running PR that tracks all changes for the library components, and maintains the versions according to [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/), generated when [PRs are merged](https://github.com/amannn/action-semantic-pull-request). When Release Please's running PR is merged, any changed artifacts are published.
1616

17-
## Developing
17+
## Contributing
1818

19-
### Requirements
20-
21-
Though we target Java 8, Java 18 is recommended for the tooling, plugins, etc. Maven 3.8+ is recommended.
22-
23-
### Testing
24-
25-
Run `mvn verify` to test, generate javadoc, and check style. If this passes locally, the CI will generally pass.
26-
27-
### Adding a module
28-
29-
1. Create a [standard directory structure](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html) in the appropriate folder (`hooks/`, `providers/`).
30-
1. Create a new `pom.xml` in the root of your new module. It must inherit from the parent POM, which implements the javadoc, testing, publishing, and other boilerplate. Be sure to add `<!--x-release-please-version -->` on the line specifying the module version, so our release tooling can update it (see sample pom below).
31-
1. Add the new package to `release-please-config.json`.
32-
1. Add the new module to the `<modules>...</modules>` section in the parent `pom.xml`.
33-
1. Add a `version.txt` file with a version matching that in your new `pom.xml`, e.g. `0.0.1`.
34-
2. If you care to release a pre 1.0.0 version, add the same version above to `.release-please-manifest.json`. Failing to do this will release a `1.0.0` initial release.
35-
36-
Sample pom.xml:
37-
38-
```xml
39-
<?xml version="1.0" encoding="UTF-8"?>
40-
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
41-
<modelVersion>4.0.0</modelVersion>
42-
<modelVersion>4.0.0</modelVersion>
43-
<parent>
44-
<groupId>dev.openfeature.contrib</groupId>
45-
<artifactId>parent</artifactId>
46-
<version><!-- current parent pom version --></version>
47-
<relativePath>../../pom.xml</relativePath>
48-
</parent>
49-
<!-- The group id MUST start with dev.openfeature, or publishing will fail. OpenFeature has verified ownership of this (reversed) domain. -->
50-
<groupId>dev.openfeature.contrib.${providers | hooks | etc}</groupId>
51-
<artifactId>module</artifactId>
52-
<version>0.0.1</version> <!--x-release-please-version -->
53-
54-
<name>module</name>
55-
<description>Your module description</description>
56-
<url>https://openfeature.dev</url>
57-
58-
<developers>
59-
<developer>
60-
<id>Your GitHub ID</id>
61-
<name>Your Name</name>
62-
<organization>OpenFeature</organization>
63-
<url>https://openfeature.dev/</url>
64-
</developer>
65-
</developers>
66-
67-
<dependencies>
68-
<!-- dependencies your module needs (in addition to those inherited from parent) -->
69-
</dependencies>
70-
71-
<build>
72-
<plugins>
73-
<!-- plugins your module needs (in addition to those inherited from parent) -->
74-
</plugins>
75-
</build>
76-
77-
</project>
78-
```
79-
80-
### VS Code config
81-
82-
To use vscode, install the standard [Java language support extension by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java).
83-
84-
The following vscode settings are recommended (create a workspace settings file at .vscode/settings.json):
85-
86-
```json
87-
{
88-
"java.configuration.updateBuildConfiguration": "interactive",
89-
"java.autobuild.enabled": false,
90-
"java.checkstyle.configuration": "${workspaceFolder}/checkstyle.xml",
91-
"java.checkstyle.version": "10.3.2",
92-
"java.format.settings.url": "${workspaceFolder}/eclipse-java-google-style.xml",
93-
"java.format.enabled": false
94-
}
95-
```
19+
see: [CONTRIBUTING.md](./CONTRIBUTING.md)
9620

9721
## License
9822

0 commit comments

Comments
 (0)