Skip to content

Commit dd062ae

Browse files
riccardo-forinariccardo-forina
committed
Update CONTRIBUTING.md
Add a CONTRIBUTING.md file for both the API and the UI module, and point the root one to them
1 parent bd1a062 commit dd062ae

File tree

4 files changed

+93
-117
lines changed

4 files changed

+93
-117
lines changed

‎CONTRIBUTING.md

+5-53
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
## Contributing to the project
1+
# Contributing to the project
22

33
**Want to contribute? Great!**
44
We try to make it easy, and all contributions, even the smaller ones, are more than welcome.
@@ -42,58 +42,10 @@ All submissions, including submissions by project members, need to be reviewed b
4242

4343
[GitHub Pull Request Review Process](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) is followed for every pull request.
4444

45-
### Coding Guidelines
45+
## Contribute to the API
4646

47-
* We decided to disallow `@author` tags in the Javadoc: they are hard to maintain
48-
* Please properly squash your pull requests before submitting them. Fixup commits can be used temporarily during the review process but things should be squashed at the end to have meaningful commits.
47+
Please check the [api/CONTRIBUTING.md](./api/CONTRIBUTING.md) file for detailed information about how to contribute to the API module.
4948

50-
### Continuous Integration
51-
52-
kafka-admin-api CI is based on GitHub Actions, which means that everyone has the ability to automatically execute CI in their forks as part of the process of making changes. We ask that all non-trivial changes go through this process, so that the contributor gets immediate feedback, while at the same time keeping our CI fast and healthy for everyone.
53-
54-
### Tests and documentation are not optional
55-
56-
Don't forget to include tests in your pull requests.
57-
Also don't forget the documentation (reference documentation, javadoc...).
58-
59-
### Installing Checkstyle
60-
61-
Project uses checkstyle mvn plugin that is executed during `mvn validate` pase.
62-
Please follow your ide setup for checkstyle. For example for intelij:
63-
64-
https://plugins.jetbrains.com/plugin/1065-checkstyle-idea
65-
66-
## Regenerating OpenAPI file
67-
68-
PRs that make changes in the API should update openapi file by executing:
69-
70-
```
71-
mvn -Popenapi-generate process-classes
72-
```
73-
74-
Please commit generated files along with the PR for review.
75-
76-
### Interacting with local kafka
77-
78-
1. Creating topic
79-
80-
```
81-
kafka-topics.sh --create --bootstrap-server localhost:9092 --partitions=3 --replication-factor=1 --topic test --command-config ./hack/binscripts.properties
82-
```
83-
84-
2. Produce messages using kcat
85-
```
86-
kcat -b localhost:9092 -F ./hack/kcat.properties -P -t test
87-
```
88-
89-
90-
4. Consume messages
91-
```
92-
kcat -b localhost:9092 -F ./hack/kcat.properties -C -t test
93-
```
94-
95-
6. Interact with the API to view results
96-
`
97-
curl -s -u admin:admin-secret http://localhost:8080/api/v1/consumer-groups | jq
98-
`
49+
## Contribute to the UI
9950

51+
Please check the [ui/CONTRIBUTING.md](./ui/CONTRIBUTING.md) file for detailed information about how to contribute to the UI module.

‎README.md

+4-58
Original file line numberDiff line numberDiff line change
@@ -6,68 +6,14 @@ It is composed of two main parts:
66
- a REST API backend developed with Java Quarkus
77
- a user interface (UI) built with Next.js and [PatternFly](https://patternfly.org)
88

9-
### Getting started
9+
## Installing
1010

11-
#### API
12-
13-
Ensure you have Kubernetes and Strimzi Cluster Operator installed on your system.
14-
15-
```bash
16-
cd api
17-
```
18-
19-
Create a `.env` file containing the details about how the API should connect to the Kafka cluster.
20-
For a Kafka cluster installed using [Strimzi's Quick Starts](https://strimzi.io/quickstarts/) it should look like this:
21-
22-
```.dotenv
23-
CONSOLE_KAFKA_MY_CLUSTER=kafka/my-cluster
24-
CONSOLE_KAFKA_MY_CLUSTER_BOOTSTRAP_SERVERS=my-cluster-kafka-bootstrap:9092
25-
```
26-
27-
Then run the application.
28-
29-
```bash
30-
./mvn quarkus:dev -DskipTests
31-
```
32-
33-
This should result in Quarkus starting up, with the REST APIs available on localhost port 8080:
34-
35-
* [API documentation](http://localhost:8080/swagger-ui)
36-
37-
#### UI
38-
39-
```bash
40-
cd ui
41-
```
42-
43-
Create a `.env` file containing the details about where to find the API server, and some additional config.
44-
45-
```.dotenv
46-
BACKEND_URL=http://localhost:8080
47-
CONSOLE_METRICS_PROMETHEUS_URL=http://localhost:9090
48-
NEXTAUTH_SECRET=abcdefghijklmnopqrstuvwxyz1234567890=
49-
LOG_LEVEL=info
50-
```
51-
52-
[!WARNING]
53-
Please generate a valid and secure value for `NEXTAUTH_SECRET`. We suggest running `openssl rand -base64 32` to get started.
54-
55-
Then run the application.
56-
57-
```bash
58-
npm install
59-
npm run dev
60-
```
61-
62-
This will start up the UI in development mode, hosted on port 3000 of your localhost:
63-
64-
## [User Interface](http://localhost:3000)
65-
66-
For more information on the UI, see the UI module's [README.md](ui/README.md).
11+
Please refer to the [install/README.md](./install/README.md) file for detailed information about how to install the Console.
6712

6813
## Contributing
6914

70-
We welcome contributions of all forms. Please see the CONTRIBUTING.md file for how to get started. Join us in enhancing the capabilities of this console for Apache Kafka™ on Kubernetes.
15+
We welcome contributions of all forms. Please see the [CONTRIBUTING.md](./CONTRIBUTING.md) file for how to get started.
16+
Join us in enhancing the capabilities of this console for Apache Kafka™ on Kubernetes.
7117

7218
## License
7319

‎api/CONTRIBUTING.md

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Contributing to the API
2+
3+
## Before you start
4+
5+
Please check the project's [contributing guide](../CONTRIBUTING.md) first.
6+
7+
## Prerequisites
8+
9+
Ensure you have Kubernetes and Strimzi Cluster Operator installed on your system.
10+
One option to get started is to follow [Strimzi's Quick Starts](https://strimzi.io/quickstarts/).
11+
12+
You will also need a working installation of:
13+
14+
- Java (v17)
15+
- Maven (v3.8)
16+
17+
### Coding Guidelines
18+
19+
* We decided to disallow `@author` tags in the Javadoc: they are hard to maintain
20+
* Please properly squash your pull requests before submitting them. Fixup commits can be used temporarily during the review process but things should be squashed at the end to have meaningful commits.
21+
22+
### Continuous Integration
23+
24+
kafka-admin-api CI is based on GitHub Actions, which means that everyone has the ability to automatically execute CI in their forks as part of the process of making changes. We ask that all non-trivial changes go through this process, so that the contributor gets immediate feedback, while at the same time keeping our CI fast and healthy for everyone.
25+
26+
### Tests and documentation are not optional
27+
28+
Don't forget to include tests in your pull requests.
29+
Also don't forget the documentation (reference documentation, javadoc...).
30+
31+
### Installing Checkstyle
32+
33+
Project uses checkstyle mvn plugin that is executed during `mvn validate` pase.
34+
Please follow your ide setup for checkstyle. For example for intelij:
35+
36+
https://plugins.jetbrains.com/plugin/1065-checkstyle-idea
37+
38+
## Regenerating OpenAPI file
39+
40+
PRs that make changes in the API should update openapi file by executing:
41+
42+
```
43+
mvn -Popenapi-generate process-classes
44+
```
45+
46+
Please commit generated files along with the PR for review.
47+
48+
### Interacting with local kafka
49+
50+
1. Creating topic
51+
52+
```
53+
kafka-topics.sh --create --bootstrap-server localhost:9092 --partitions=3 --replication-factor=1 --topic test --command-config ./hack/binscripts.properties
54+
```
55+
56+
2. Produce messages using kcat
57+
```
58+
kcat -b localhost:9092 -F ./hack/kcat.properties -P -t test
59+
```
60+
61+
62+
4. Consume messages
63+
```
64+
kcat -b localhost:9092 -F ./hack/kcat.properties -C -t test
65+
```
66+
67+
6. Interact with the API to view results
68+
`
69+
curl -s -u admin:admin-secret http://localhost:8080/api/v1/consumer-groups | jq
70+
`
71+

‎ui/README.md ‎ui/CONTRIBUTING.md

+13-6
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,27 @@
22

33
This part of the project contains the user interface for the Kafka console, developed using Next.js and the [PatternFly](https://patternfly.org) UI library.
44

5+
## Prerequisites
6+
7+
Please make sure you have working installations of:
8+
9+
- node (v18+)
10+
- npm (v10+)
11+
12+
To run a development version of the UI working in all its sections, you will need to install the console on a development cluster first. Please refer to the [install/README.md](../install/README.md) file for detailed instructions about how to do it.
13+
14+
Alternatively, you can run the API module locally, but sections depending on the metrics exported on Prometheus will not work correctly.
15+
516
## Getting Started
617

718
Create a `.env` file containing the details about where to find the API server, and some additional config.
819

920
```.dotenv
10-
BACKEND_URL=http://localhost:8080
21+
BACKEND_URL=http://:8080
1122
CONSOLE_METRICS_PROMETHEUS_URL=http://localhost:9090
12-
NEXTAUTH_SECRET=abcdefghijklmnopqrstuvwxyz1234567890=
1323
LOG_LEVEL=info
1424
```
1525

16-
[!WARNING]
17-
Please generate a valid and secure value for `NEXTAUTH_SECRET`. We suggest running `openssl rand -base64 32` to get started.
18-
1926
Install the required dependencies.
2027

2128
```bash
@@ -89,4 +96,4 @@ npm run build
8996
npm run test
9097
```
9198

92-
This will run Playwright against a production build of the application.
99+
This will run Playwright against a production build of the application.

0 commit comments

Comments
 (0)