Add a top-level README, update contribution documentation #611

riccardo-forina · 2024-03-21T15:20:13Z

Also update the UI README to be more meaningful

andreaTP

Great start! A few comments around 🙂

README.md

andreaTP · 2024-03-21T15:23:49Z

README.md

+
+#### API
+
+Ensure you have Kubernetes and Strimzi Cluster Operator installed on your system.


I think we should give at least a "starting point" of a "demo" supported configuration? E.g. install minikube, install strimzi etc. etc.

README.md

andreaTP · 2024-03-21T15:29:34Z

README.md

+Ensure you have Kubernetes and Strimzi Cluster Operator installed on your system.
+
+```bash
+cd api


are you sure that we want the user to run everything in "dev mode"?
I guess, it would be easier to run things as containers in the cluster, and reserve those instructions for a Contributing document.

andreaTP · 2024-03-21T15:41:14Z

README.md

+Then run the application. 
+
+```bash
+./mvn quarkus:dev -DskipTests


this is dev mode and requires a bunch of dependencies, e.g. a compatible JDK installed globally, either we remove the requirement or we add a section Pre-requisites in this document.

andreaTP · 2024-03-21T15:46:10Z

README.md

+
+```bash
+npm install
+npm run dev


Those commands require some development toolchain to be installed, node, npm versions etc. etc.
I keep being convinced that running in dev mode requires a level of effort that people simply "checking out the project" do not want to invest.
We should strive to make the Quick start as simple and with as little requirements as possible to reduce this friction.

andreaTP · 2024-03-21T15:48:52Z

ui/README.md

+Create a `.env` file containing the details about where to find the API server, and some additional config.
+
+```.dotenv
+BACKEND_URL=http://localhost:8080


This content looks duplicated, keeping the documentation up to date requires maintenance and we wanna minimize it.
Either you keep these information in one place or you put in place automation to keep the text synced.

ui/README.md

andreaTP · 2024-03-21T15:50:15Z

ui/README.md

+
+This will create an optimized version of the application that can be deployed.
+
+## Developing the UI

 ```bash
 npm run dev


what are the requirements?

andreaTP · 2024-03-21T15:53:01Z

ui/README.md


-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
+This will run Playwright against a production build of the application. 


Suggested change

This will run Playwright against a production build of the application.

This will run E2E tests(powered by [Playwright](https://playwright.dev/)) against a production build of the application.

a production build of the application

how can I get one?

README.md

riccardo-forina · 2024-03-21T16:18:56Z

README.md

+```.dotenv
+BACKEND_URL=http://localhost:8080
+CONSOLE_METRICS_PROMETHEUS_URL=http://localhost:9090
+NEXTAUTH_SECRET=abcdefghijklmnopqrstuvwxyz1234567890=


Suggested change

NEXTAUTH_SECRET=abcdefghijklmnopqrstuvwxyz1234567890=

# the UI uses next-auth for authentication, this variable is required to run the app. Doc here https://next-auth.js.org/configuration/options#secret

NEXTAUTH_SECRET=abcdefghijklmnopqrstuvwxyz1234567890=

riccardo-forina · 2024-03-21T16:21:26Z

README.md

+```
+
+[!WARNING]
+Please generate a valid and secure value for `NEXTAUTH_SECRET`. We suggest running `openssl rand -base64 32` to get started.


Suggested change

Please generate a valid and secure value for `NEXTAUTH_SECRET`. We suggest running `openssl rand -base64 32` to get started.

Please generate a valid and secure value for `NEXTAUTH_SECRET`. We suggest running `openssl rand -base64 32` to get started. More details on [Next.js documentation](https://next-auth.js.org/configuration/options#secret)

api/CONTRIBUTING.md

andreaTP · 2024-03-22T15:49:51Z

ui/CONTRIBUTING.md

+- 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.


I'm confused, the ./install/README file mentions yet another way of installing things, and is not clear what to use when.

Also what's "the console" here?

andreaTP · 2024-03-22T15:52:10Z

ui/CONTRIBUTING.md

+npm run test
+```
+
+This will run Playwright against a production build of the application. 


what's a "production build" in this context?

andreaTP · 2024-03-22T15:53:45Z

ui/CONTRIBUTING.md

+npm run start
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the console.


is console the UI?

MikeEdgar

A few comments. It would be good to merge this one. I also have some work to add a compose file that will need to be documented in the new README as well.

api/CONTRIBUTING.md

MikeEdgar · 2024-05-13T18:29:59Z

api/CONTRIBUTING.md

+## 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.
+


This section can be removed.

Suggested change

## 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.

api/CONTRIBUTING.md

MikeEdgar · 2024-05-13T18:41:44Z

quickstart/01-kafka.yaml

+apiVersion: kafka.strimzi.io/v1beta2
+kind: Kafka


These don't seem to be referenced and are similar to what we already have in the install directory. Are they needed?

Co-authored-by: Andrea Peruffo <[email protected]>

Add a CONTRIBUTING.md file for both the API and the UI module, and point the root one to them

Signed-off-by: Michael Edgar <[email protected]>

sonarqubecloud · 2024-05-15T14:50:57Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
No data about Duplication

See analysis details on SonarCloud

MikeEdgar · 2024-05-15T15:00:05Z

Merging for now to have the structure in place. We'll refine this documentation moving forward.

riccardo-forina requested a review from MikeEdgar March 21, 2024 15:20

andreaTP suggested changes Mar 21, 2024

View reviewed changes

riccardo-forina commented Mar 21, 2024

View reviewed changes

README.md Outdated Show resolved Hide resolved

riccardo-forina commented Mar 21, 2024

View reviewed changes

riccardo-forina force-pushed the readme branch 3 times, most recently from 4bcc603 to b8017f6 Compare March 21, 2024 16:53

andreaTP reviewed Mar 22, 2024

View reviewed changes

riccardo-forina force-pushed the readme branch from e56c18e to e97ed60 Compare April 16, 2024 09:29

MikeEdgar reviewed May 13, 2024

View reviewed changes

MikeEdgar force-pushed the readme branch from e97ed60 to 625e7d2 Compare May 15, 2024 14:34

MikeEdgar approved these changes May 15, 2024

View reviewed changes

MikeEdgar changed the title ~~Add a top-level README~~ Add a top-level README, update contribution documentation May 15, 2024

riccardo-forina and others added 8 commits May 15, 2024 10:44

Add a top-level README

40d3615

Update the README for the UI

3b827e2

Update README.md

8e344a8

Co-authored-by: Andrea Peruffo <[email protected]>

Update CONTRIBUTING.md

ee4fd05

Add a CONTRIBUTING.md file for both the API and the UI module, and point the root one to them

Improve the API contributing doc

aef3a11

Ignore env files across all repo

0731f53

Add CRs to quickly deploy the console on a local development environment

51abc53

Minor updates - add links, delete outdated instructions

3e32a97

Signed-off-by: Michael Edgar <[email protected]>

MikeEdgar force-pushed the readme branch from 625e7d2 to 3e32a97 Compare May 15, 2024 14:44

MikeEdgar merged commit 662478f into main May 15, 2024
11 of 12 checks passed

MikeEdgar deleted the readme branch May 15, 2024 15:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a top-level README, update contribution documentation #611

Add a top-level README, update contribution documentation #611

riccardo-forina commented Mar 21, 2024

andreaTP left a comment

andreaTP Mar 21, 2024

andreaTP Mar 21, 2024

andreaTP Mar 21, 2024

andreaTP Mar 21, 2024

andreaTP Mar 21, 2024

andreaTP Mar 21, 2024

andreaTP Mar 21, 2024

riccardo-forina Mar 21, 2024 •

edited

Loading

riccardo-forina Mar 21, 2024

andreaTP Mar 22, 2024

andreaTP Mar 22, 2024

andreaTP Mar 22, 2024

andreaTP Mar 22, 2024

MikeEdgar left a comment

MikeEdgar May 13, 2024

MikeEdgar May 13, 2024

sonarqubecloud bot commented May 15, 2024

MikeEdgar commented May 15, 2024


		#### API

		Ensure you have Kubernetes and Strimzi Cluster Operator installed on your system.


		Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
		This will run Playwright against a production build of the application.

	This will run Playwright against a production build of the application.
	This will run E2E tests(powered by [Playwright](https://playwright.dev/)) against a production build of the application.

	NEXTAUTH_SECRET=abcdefghijklmnopqrstuvwxyz1234567890=
	# the UI uses next-auth for authentication, this variable is required to run the app. Doc here https://next-auth.js.org/configuration/options#secret
	NEXTAUTH_SECRET=abcdefghijklmnopqrstuvwxyz1234567890=

	Please generate a valid and secure value for `NEXTAUTH_SECRET`. We suggest running `openssl rand -base64 32` to get started.
	Please generate a valid and secure value for `NEXTAUTH_SECRET`. We suggest running `openssl rand -base64 32` to get started. More details on [Next.js documentation](https://next-auth.js.org/configuration/options#secret)

		apiVersion: kafka.strimzi.io/v1beta2
		kind: Kafka

Add a top-level README, update contribution documentation #611

Add a top-level README, update contribution documentation #611

Conversation

riccardo-forina commented Mar 21, 2024

andreaTP left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

riccardo-forina Mar 21, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MikeEdgar left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sonarqubecloud bot commented May 15, 2024

Quality Gate passed

MikeEdgar commented May 15, 2024

riccardo-forina Mar 21, 2024 •

edited

Loading