Add a top-level README, update contribution documentation

.gitignore

@@ -20,3 +20,7 @@ release.properties
 # VS Code
 .factorypath
 .vscode
+
+
+# env files
+.env*

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-## Contributing to the project
+# Contributing to the project
 
 **Want to contribute? Great!**
 We try to make it easy, and all contributions, even the smaller ones, are more than welcome.
@@ -17,7 +17,7 @@ The DCO text is also included verbatim in the [dco.txt](dco.txt) file in the roo
 
 ## Reporting an issue
 
-This project uses GitHub issues to manage the issues. Open an issue directly in GitHub. you can also open JIRA issues at https://issues.redhat.com/browse/MGDSTRM
+This project uses GitHub issues to manage the issues. Open an issue directly in GitHub.
 
 If you believe you found a bug, and it's likely possible, please indicate a way to reproduce it, what you are seeing and what you would expect to see.
 
@@ -42,58 +42,10 @@ All submissions, including submissions by project members, need to be reviewed b
 
 [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.
 
-### Coding Guidelines
+## Contribute to the API
 
- * We decided to disallow `@author` tags in the Javadoc: they are hard to maintain
- * 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.
+Please check the [api/CONTRIBUTING.md](./api/CONTRIBUTING.md) file for detailed information about how to contribute to the API module.
 
-### Continuous Integration
-
- 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.
-
-### Tests and documentation are not optional
-
-Don't forget to include tests in your pull requests.
-Also don't forget the documentation (reference documentation, javadoc...).
-
-### Installing Checkstyle
-
-Project uses checkstyle mvn plugin that is executed during `mvn validate` pase.
-Please follow your ide setup for checkstyle. For example for intelij:
-
-https://plugins.jetbrains.com/plugin/1065-checkstyle-idea
-
-## Regenerating OpenAPI file
-
-PRs that make changes in the API should update openapi file by executing:
-
-```
-mvn -Popenapi-generate process-classes
-```
-
-Please commit generated files along with the PR for review.
-
-### Interacting with local kafka
-
-1. Creating topic
-
-```
-kafka-topics.sh --create --bootstrap-server localhost:9092  --partitions=3 --replication-factor=1 --topic test --command-config ./hack/binscripts.properties
-```
-
-2. Produce messages using kcat
-```
-kcat -b localhost:9092 -F ./hack/kcat.properties -P -t test
-```
-
-
-4. Consume messages
-```
- kcat -b localhost:9092 -F ./hack/kcat.properties  -C -t test
-```
-
-6. Interact with the API to view results
-`
-curl -s -u admin:admin-secret http://localhost:8080/api/v1/consumer-groups | jq
-`
+## Contribute to the UI
 
+Please check the [ui/CONTRIBUTING.md](./ui/CONTRIBUTING.md) file for detailed information about how to contribute to the UI module.

README.md

@@ -0,0 +1,20 @@
+# Console for Apache Kafka™ on Kubernetes
+
+This project is a web console designed to facilitate interactions with Apache Kafka™ instances on Kubernetes, leveraging the [Strimzi](https://strimzi.io) Cluster Operator.
+It is composed of two main parts:
+
+- a REST API backend developed with Java and [Quarkus](https://quarkus.io/)
+- a user interface (UI) built with [Next.js](https://nextjs.org/) and [PatternFly](https://patternfly.org)
+
+## Installing
+
+Please refer to the [installation README](./install/README.md) file for detailed information about how to install the latest release of the console in a Kubernetes cluster.
+
+## Contributing
+
+We welcome contributions of all forms. Please see the [CONTRIBUTING](./CONTRIBUTING.md) file for how to get started.
+Join us in enhancing the capabilities of this console for Apache Kafka™ on Kubernetes.
+
+## License
+
+This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

api/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing to the API
+
+## Before you start
+
+Please check the project's [contributing guide](../CONTRIBUTING.md) first.
+
+## Prerequisites
+
+Ensure you have Kubernetes and Strimzi Cluster Operator installed on your system. Either [minikube](https://minikube.sigs.k8s.io/) or [OpenShifot Local](https://developers.redhat.com/products/openshift-local) are good options.
+One option to get started is to follow [Strimzi's Quick Starts](https://strimzi.io/quickstarts/).
+
+You will also need a working installation of:
+
+- Java (v17)
+- Maven (v3.8)
+
+### Coding Guidelines
+
+ * We decided to disallow `@author` tags in the Javadoc: they are hard to maintain
+ * 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.
+
+### Continuous Integration
+
+This project's 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.
+
+### Tests and documentation are not optional
+
+Do not forget to include or update tests in your pull requests and update any related documentation (reference documentation, javadoc...).
+
+### Installing Checkstyle
+
+Project uses checkstyle mvn plugin that is executed during `mvn validate` phase. Make sure to verify this
+passes before pushing to Github.

ui/.dockerignore

@@ -2,7 +2,7 @@ Dockerfile
 .dockerignore
 node_modules
 npm-debug.log
-README.md
+CONTRIBUTING.md
 .next
 .git
 .env.*

ui/CONTRIBUTING.md

@@ -0,0 +1,100 @@
+# Contributing to the UI
+
+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.
+
+## Prerequisites
+
+Please make sure you have working installations of:
+
+- node (v18+)
+- npm (v10+)
+
+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.
+
+Alternatively, you can run the API module locally, but sections depending on the metrics exported on Prometheus will not work correctly.
+
+## Getting Started
+
+Create a `.env` file containing the details about where to find the API server, and some additional config.
+
+```.dotenv
+# the actual URLs will depend on how you installed the console
+BACKEND_URL=http://api.my-cluster
+CONSOLE_METRICS_PROMETHEUS_URL=http://prometheus.my-cluster
+LOG_LEVEL=info
+```
+
+Install the required dependencies.
+
+```bash
+npm run install
+```
+
+Then run the application.
+
+```bash
+npm run build
+npm run start
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the console user interface.
+
+## Build
+
+```bash
+npm run build
+```
+
+This will create an optimized version of the application that can be deployed.
+
+## Developing the UI
+
+```bash
+npm run dev
+```
+
+This will start the UI in dev mode, hosted (by default) on port 3000. When running successfully, you should see output similar to:
+
+```
+[email protected] dev
+NODE_OPTIONS='-r next-logger' next dev | pino-pretty
+
+[16:11:06.206] INFO (console/14593):    ▲ Next.js 14.1.4
+[16:11:06.206] INFO (console/14593):    - Local:        http://localhost:3000
+[16:11:06.206] INFO (console/14593):    - Environments: .env.local
+[16:11:06.206] INFO (next.js/14593):
+prefix: "info"
+[16:11:08.981] INFO (next.js/14593): Ready in 2.9s
+prefix: "event"
+```
+
+You can then access the UI on port 3000 or your localhost.
+
+Note: you will need the REST API running for the UI to work. See the README at the root of this repository for examples of how to do that.
+
+### Develop the components in isolation using Storybook
+
+```bash
+npm run storybook
+```
+
+This will start Storybook, hosted on port 6006.
+
+### Test the UI
+
+```bash
+npm run build-storybook
+http-serve -p 6006 storybook-static
+
+# in a different terminal
+npm run test-storybook
+```
+
+This will build Storybook and run all the relative unit tests.
+
+```bash
+npm run build
+npm run test
+```
+
+This will run Playwright against the built application.