Documentation update (#1381)

* Update issue templates

* Update PULL_REQUEST_TEMPLATE.md

* Update PULL_REQUEST_TEMPLATE.md

* Update stale labels

* Move files, minor updates

* Moved files, minor updates

* Update bug_report.md

* Update feature_request.md

* Add roadmap document

Signed-off-by: Roman Zabaluev <rzabaluev@provectus.com>

* Update SECURITY.md

Signed-off-by: Roman Zabaluev <rzabaluev@provectus.com>

* Update stale periods

Signed-off-by: Roman Zabaluev <rzabaluev@provectus.com>

* Add a stub for guidelines for QA

Signed-off-by: Roman Zabaluev <rzabaluev@provectus.com>

* Extract building/running instructions from the readme

Signed-off-by: Roman Zabaluev <rzabaluev@provectus.com>

* move testing guidelines

Signed-off-by: Roman Zabaluev <rzabaluev@provectus.com>

* Table of contents for contributing

Signed-off-by: Roman Zabaluev <rzabaluev@provectus.com>

* Add license and release badges

Signed-off-by: Roman Zabaluev <rzabaluev@provectus.com>

* Add info about actuator endpoints

Signed-off-by: Roman Zabaluev <rzabaluev@provectus.com>

* Update logotype and slogan

Signed-off-by: Roman Zabaluev <rzabaluev@provectus.com>

* Redone contributing guide

Signed-off-by: Roman Zabaluev <rzabaluev@provectus.com>

* Minor updates

Signed-off-by: Roman Zabaluev <rzabaluev@provectus.com>

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,19 +1,21 @@
 ---
 name: "\U0001F41E  Bug report"
-about: Create a report to help us improve
-title: ''
-labels: type/bug
+about: Create a bug report
+title: "[Bug]"
+labels: status/triage, type/bug
 assignees: ''
 
 ---
 
 **Describe the bug**
-(A clear and concise description of what the bug is.)
+<!--(A clear and concise description of what the bug is.)-->
 
 
 **Set up**
+<!--
 (How do you run the app? 
 Which version of the app are you running? Provide either docker image version or check commit hash at the top left corner. We won't be able to help you without this information.)
+-->
 
 
 **Steps to Reproduce**
@@ -22,11 +24,17 @@ Steps to reproduce the behavior:
 1. 
 
 **Expected behavior**
+<!--
 (A clear and concise description of what you expected to happen)
+-->
 
 **Screenshots**
+<!--
 (If applicable, add screenshots to help explain your problem)
+-->
 
 
 **Additional context**
+<!--
 (Add any other context about the problem here)
+-->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,8 +1,8 @@
 ---
 name: "\U0001F680 Feature request"
 about: Propose a new feature
-title: ''
-labels: type/enhancement
+title: "[Feature]"
+labels: status/triage, type/feature
 assignees: ''
 
 ---
@@ -14,24 +14,18 @@ assignees: ''
   For example, "I'm always frustrated when..."
 -->
 
-(Write your answer here.)
-
 ### Describe the solution you'd like
 
 <!--
   Provide a clear and concise description of what you want to happen.
 -->
 
-(Describe your proposed solution here.)
-
 ### Describe alternatives you've considered
 
 <!--
   Let us know about other solutions you've tried or researched.
 -->
 
-(Write your answer here.)
-
 ### Additional context
 
 <!--
@@ -39,4 +33,3 @@ assignees: ''
   You might want to link to related issues here, if you haven't already.
 -->
 
-(Write your answer here.)

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,27 +1,31 @@
 <!-- ignore-task-list-start -->
-- [ ] **Breaking change?** (if so, please describe the impact and migration path for existing applications:)
+- [ ] **Breaking change?** (if so, please describe the impact and migration path for existing application instances)
+
+
 <!-- ignore-task-list-end -->
 **What changes did you make?** (Give an overview)
 
 **Is there anything you'd like reviewers to focus on?**
 
 
-**How Has This Been Tested?** (put an "X" next to an item)
+**How Has This Been Tested?** (put an "x" (case-sensitive!) next to an item)
 <!-- ignore-task-list-start -->
 - [ ] No need to
-- [ ] Manually(please, describe, when necessary)
+- [ ] Manually (please, describe, if necessary)
 - [ ] Unit checks
 - [ ] Integration checks
 - [ ] Covered by existing automation
 <!-- ignore-task-list-end -->
 
-**Checklist** (put an "X" next to an item, otherwise PR will fail)
+**Checklist** (put an "x" (case-sensitive!) next to all the items, otherwise the build will fail)
 - [ ] I have performed a self-review of my own code
 - [ ] I have commented my code, particularly in hard-to-understand areas
 - [ ] I have made corresponding changes to the documentation (e.g. **ENVIRONMENT VARIABLES**)
-- [ ] My changes generate no new warnings(e.g. Sonar is happy)
+- [ ] My changes generate no new warnings (e.g. Sonar is happy)
 - [ ] I have added tests that prove my fix is effective or that my feature works
 - [ ] New and existing unit tests pass locally with my changes
 - [ ] Any dependent changes have been merged
 
-Check out [Contributing](https://github.com/provectus/kafka-ui/blob/master/CONTRIBUTING.md) and [Code of Conduct](https://github.com/provectus/kafka-ui/blob/master/CODE-OF-CONDUCT.md)
+Check out [Contributing](https://github.com/provectus/kafka-ui/blob/master/CONTRIBUTING.md) and [Code of Conduct](https://github.com/provectus/kafka-ui/blob/master/CODE-OF-CONDUCT.md)
+
+**A picture of a cute animal (not mandatory but encouraged)**

.github/stale.yml

@@ -1,13 +1,14 @@
 # Number of days of inactivity before an issue becomes stale
-daysUntilStale: 30
+daysUntilStale: 7
 # Number of days of inactivity before a stale issue is closed
-daysUntilClose: 7
+daysUntilClose: 3
 # Only issues or pull requests with all of these labels are check if stale. Defaults to `[]` (disabled)
 onlyLabels:
   - 'status/pending'
 # Issues with these labels will never be considered stale
 exemptLabels:
   - 'status/on-hold'
+  - 'status/blocked'
   - 'status/triage'
   - 'type/security'
 # Label to use when marking an issue as stale

CONTRIBUTING.md

@@ -1,44 +1,94 @@
-# Contributing
+The following guide is aimed at explaining the process of working on an issue(-s) and Pull Requests (PRs).
 
-When contributing to this repository, please first discuss the change you wish to make via issue,
-email, or any other method with the maintainers of the repository before making a change. 
+Completing some of the steps isn't possible by yourself if you don't have a write permission. Feel free to ask the maintainers to help you out with the unavailable actions.
+
+# General recommendations
 
 Please note we have a code of conduct (`CODE-OF-CONDUCT.md`), please follow it in all your interactions with the project.
 
-## Pull Request Process
 
-### General rules
+# Issues
 
-1. Ensure any install or build dependencies have been removed before the end of the layer when composing a 
-   build.
-2. Update the `README.md` with details of changes to the interface, this includes new environment 
-   variables, exposed ports, useful file locations and container parameters.
-3. Start a pull request name with issue number (ex. #123).
-4. You may merge the pull request once you have the approval of two other developers. In case you 
-   don't have permissions to do that, you may request the second reviewer to merge it for you.
+## Choosing an issue
+
+Basically, there are two places to look up for the issues to contribute to. <br/>
+The first one is our ["Up for grabs"](https://github.com/provectus/kafka-ui/projects/11) board, where issues are sorted by required experience level (beginner, intermediate, expert).
+
+The second place is searching up for ["good first issue"](https://github.com/provectus/kafka-ui/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)-labeled issues. Some of them might not be present in the aforementioned board or vice versa.
+
+The next thing to consider is labels. You can sort the issues by scope labels, like, `scope/backend`, `scope/frontend` or even `scope/k8s`. If the issue requires a few areas to work on, and you don't have a required expertise, still feel free to pick it and do your part, others will do the rest.
+
+## Grabbing the issue
+
+There is a bunch of criteria for an issue to be liable for development. <br/>
+The implementation of the features and/or their enhancements should be reasonable, must be backed by justified requirements (demanded by community, [roadmap](documentation/project/ROADMAP.md) plans, etc.). Final decision is left for maintainers' discretion. <br/>
+All the bugs should be confirmed as such (that the behavior is unintended).
+
+The issue should be properly triaged by maintainers beforehand, which includes:
+1. Having a proper milestone set
+2. Having required labels assigned: accepted label, scope labels and others.
+
+Formally, having the aforementioned triage conditions is enough to get started.
+
+Having all these requirements present, feel free to pick the issue you want. Ask the maintainers in case of doubt.
+
+## Working on the issue
+
+Every issue which is being worked on has to be assigned to the corresponding person. <br/>
+To keep the status of the issue clear, please keep the card' status actual ("project" card on the right side of the issue, should be the same as the milestone name).
 
-### Branch naming
+## Setting up a local development environment
+
+Please refer to [this guide](documentation/project/contributing/README.md).
+
+# Pull Requests
+
+## Branch naming
 
 In order to keep branch names understandable and similar please use the corresponding branch naming conventions.
 
-Generally speaking, it's a good idea to add a group/type prefix for a branch, e.g., 
-if you're working on a specific branch you could name your branch `issues/xxx`. 
+Generally speaking, it's a good idea to add a group/type prefix for a branch, e.g.,
+if you're working on a specific branch you could name your branch `issues/xxx`.
 
 Here's a list of good examples:<br/>
 `issues/123`<br/>
 `feature/feature_name`<br/>
 `bugfix/fix_thing`<br/>
 
-### Code style
+## Code style
 
-There's a file called `checkstyle.xml` in project root under `etc` directory.<br/>
-You can import it into IntelliJ IDEA via checkstyle plugin. 
+Java: There's a file called `checkstyle.xml` in project root under `etc` directory.<br/>
+You can import it into IntelliJ IDEA via checkstyle plugin.
 
-### Naming conventions
+## Naming conventions
 
 REST paths should be **lowercase** and consist of just **plural** nouns.<br/>
 Also, multiple words in a single path segment should be divided by a hyphen symbol (`-`).<br/>
 
 Query variable names should be formatted in `camelCase`.
 
-Model names should consist of just **plural** nouns and should be formatted in `camelCase` as well.
+Model names should consist of just **plural** nouns and should be formatted in `camelCase` as well.
+
+## Creating a PR
+
+When creating a PR please do the following:
+1. In commit messages use the [closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword).
+2. Link an issue(-s) via "linked issues" block.
+3. Set the PR labels. Just set the same set of labels present in the issue, ignoring yellow `status/` labels.
+4. If the PR doesn't close any issue it might need to a milestone set on itself. Ask the maintainers.
+5. Assign the PR to yourself. PR assignee is the person who's goal is to get the PR merged.
+6. Add reviewers. Usually, reviewers suggestions are pretty good, use them.
+
+### Pull Request checklist
+
+1. Ensure any install or build dependencies have been removed before the end of the layer when composing a build.
+2. Update the `README.md` with details of changes to the interface, this includes new environment
+   variables, exposed ports, useful file locations and container parameters.
+
+## Reviewing a PR
+
+WIP
+
+### Pull Request reviewer checklist
+
+WIP

README.md

@@ -1,7 +1,10 @@
-![UI for Apache Kafka logo](images/kafka-ui-logo.png) UI for Apache Kafka – Free Web UI for Apache Kafka   
+![UI for Apache Kafka logo](documentation/images/kafka-ui-logo.png) UI for Apache Kafka 
 ------------------
+#### Versatile, fast and lightweight web UI for managing Apache Kafka® clusters. Built by developers, for developers.
 
-![UI for Apache Kafka Price Free](images/free-open-source.svg)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/provectus/kafka-ui/blob/master/LICENSE)
+![UI for Apache Kafka Price Free](documentation/images/free-open-source.svg)
+[![Release version](https://img.shields.io/github/v/release/provectus/kafka-ui)](https://github.com/provectus/kafka-ui/releases)
 [![Chat with us](https://img.shields.io/discord/897805035122077716)](https://discord.gg/4DWzD7pGE5)
 
 <em>UI for Apache Kafka is a free, open-source web UI to monitor and manage Apache Kafka clusters. </em> 
@@ -11,7 +14,7 @@ UI for Apache Kafka is a simple tool that makes your data flows observable, help
 Set up UI for Apache Kafka with just a couple of easy commands to visualize your Kafka data in a comprehensible way. You can run the tool locally or in 
 the cloud. 
 
-![Interface](images/Interface.gif)
+![Interface](documentation/images/Interface.gif)
 
 # Features
 * **Multi-Cluster Management** — monitor and manage all your clusters in one place
@@ -26,6 +29,8 @@ the cloud.
 # The Interface
 UI for Apache Kafka wraps major functions of Apache Kafka with an intuitive user interface.
 
+![Interface](documentation/images/Interface.gif)
+
 ## Topics
 UI for Apache Kafka makes it easy for you to create topics in your browser by several clicks, 
 pasting your own parameters, and viewing topics in the list.
@@ -45,7 +50,7 @@ Let's say we want to produce messages for our topic. With the UI for Apache Kafk
 ## Schema registry
 There are 3 supported types of schemas: Avro®, JSON Schema, and Protobuf schemas.
 
-![Create Schema Registry](images/Create_schema.gif)
+![Create Schema Registry](documentation/images/Create_schema.gif)
 
 Before producing avro-encoded messages, you have to add an avro schema for the topic in Schema Registry. Now all these steps are easy to do 
 with a few clicks in a user-friendly interface.
@@ -114,61 +119,17 @@ If you prefer to use `docker-compose` please refer to the [documentation](docker
 
 ## Building With Docker
 
-Steps to build UI for Apache Kafka locally with Docker:  
-
-1. Install prerequisites: Java and Docker
-2. Clone this repository and open a terminal in the directory of the project
-3. Build a Docker container with UI for Apache Kafka
-4. Start UI for Apache Kafka with your Kafka clusters
-5. Navigate to UI for Apache Kafka 
-
 ### Prerequisites
 
-* Java 13 or newer
-* Docker 
+Check [software-required.md](documentation/software-required.md)
 
-### Installing Prerequisites on Mac
-1. Install Homebrew Cask:
-```sh
-> brew update
-``` 
-2. Install JAVA 13 with Homebrew Cask:
-```sh
-> brew tap adoptopenjdk/openjdk
-> brew install adoptopenjdk13
-``` 
 ### Building
 
-Once you installed the prerequisites and cloned the repository, run the following commands in your project directory: 
-
-Build a Docker container with UI for Apache Kafka: 
-```sh
-./mvnw clean install -Pprod
-``` 
-Start UI for Apache Kafka with your Kafka clusters: 
-```sh
-docker-compose -f ./docker/kafka-ui.yaml up
-``` 
-To see UI for Apache Kafka, navigate to http://localhost:8080.
-
-If you want to start only kafka-clusters: 
-```sh
-docker-compose -f ./docker/kafka-clusters-only.yaml up
-``` 
-Then start UI for Apache Kafka with a **local** profile. 
+Check [building.md](documentation/building.md)
 
-## Running Locally Without Docker
+### Running
 
-```sh
-./mvnw spring-boot:run -Pprod
-``` 
-
-## Running in Kubernetes
-``` bash
-helm repo add kafka-ui https://provectus.github.io/kafka-ui
-helm install kafka-ui kafka-ui/kafka-ui
-```
-To read more please follow to [chart documentation](charts/kafka-ui/README.md)
+Check [running.md](documentation/running.md)
 
 # Guides
 
@@ -182,6 +143,10 @@ UI for Apache Kafka supports TLS (SSL) and SASL connections for [encryption and
 
 To be continued
 
+## Liveliness and readiness probes
+Liveliness and readiness endpoint is at `/actuator/health`.
+Info endpoint (build info) is located at `/actuator/info`.
+
 ## <a name="env_variables"></a> Environment Variables
 
 Alternatively, each variable of the .yml file can be set with an environment variable. 

SECURITY.md

@@ -2,8 +2,7 @@
 
 ## Supported Versions
 
-Use this section to tell people about which versions of your project are
-currently being supported with security updates.
+Following versions of the project are currently being supported with security updates.
 
 | Version | Supported          |
 | ------- | ------------------ |
@@ -13,6 +12,6 @@ currently being supported with security updates.
 
 ## Reporting a Vulnerability
 
-Please report all sensitive security vulnerabilities via email (maintainers.kafka-ui "at" provectus.com).
+Please **DO NOT** file a publicly available github issues regarding security vulnerabilities.
+Send us details via email (maintainers.kafka-ui "at" provectus.com).
 Consider adding something like "security vulnerability report" in the title of an email.
-If we haven't answered you in 48 hours (excluding weekends), please kindly remind us via an issue (without security details).

docker-openjdk/Dockerfile

@@ -1,3 +0,0 @@
-FROM openjdk:13
-RUN  yum install -y git && \
-     yum groupinstall -y "Development Tools"

documentation/project/ROADMAP.md

@@ -0,0 +1,22 @@
+Kafka-UI Project Roadmap
+====================
+
+Roadmap exists in a form of a github project board and is located [here](https://github.com/provectus/kafka-ui/projects/8).
+
+### How to use this document
+
+The roadmap provides a list of features we decided to prioritize in project development. It should serve as a reference point to understand projects' goals.
+
+We do prioritize them based on the feedback from the community, our own vision and other conditions and circumstances. 
+
+The roadmap sets the general way of development. The roadmap is mostly about long-term features. All the features could be re-prioritized, rescheduled or canceled.
+
+If there's no feature `X`, that **doesn't** mean we're **not** going to implement it. Feel free to raise the issue for the consideration. <br/>
+If a feature you want to see live is not present on roadmap, but there's an issue for the feature, feel free to vote for it using reactions in the issue.
+
+
+### How to contribute
+
+Since the roadmap consists mostly of big long-term features, implementing them might be not easy for a beginner outside collaborator.
+
+A good starting point is checking the [CONTRIBUTING.md](https://github.com/provectus/kafka-ui/blob/master/CONTRIBUTING.md) document.

documentation/project/contributing/README.md

@@ -0,0 +1,9 @@
+# Contributing guidelines
+
+### Set up the local environment for development
+
+* [Prerequisites](software-required.md)
+<!--* [Setting up git](set-up-git.md)-->
+* [Building the app](building.md)
+* [Running the app](running.md)
+* [Writing tests](testing.md)

documentation/project/contributing/building.md

@@ -0,0 +1,23 @@
+### Building the application locally
+
+Once you installed the prerequisites and cloned the repository, run the following commands in your project directory:
+
+Build a docker container with the app:
+```sh
+./mvnw clean install -Pprod
+``` 
+Start the app with Kafka clusters:
+```sh
+docker-compose -f ./docker/kafka-ui.yaml up -d
+``` 
+To see the app, navigate to http://localhost:8080.
+
+If you want to start only kafka clusters (to run the app via `boot:run`):
+```sh
+docker-compose -f ./docker/kafka-clusters-only.yaml up -d
+``` 
+Then start the app with a **local** profile. 
+
+## Where to go next
+
+In the next section, you'll [learn how to run the application](running.md).

documentation/project/contributing/running.md

@@ -0,0 +1,21 @@
+# Running the app
+
+### Running locally via docker
+If you have built a container locally or wish to run a public one you could bring everything up like this:
+```shell
+docker-compose -f docker/kafka-ui.yaml up -d
+```
+
+### Running locally without docker
+Once you built the app, run the following:
+
+```sh
+./mvnw spring-boot:run -Pprod
+```
+
+### Running in kubernetes
+``` bash
+helm repo add kafka-ui https://provectus.github.io/kafka-ui
+helm install kafka-ui kafka-ui/kafka-ui
+```
+To read more please follow to [chart documentation](charts/kafka-ui/README.md)

documentation/project/contributing/set-up-git.md

@@ -0,0 +1,8 @@
+### Nothing special here yet.
+<!--
+TODO:
+
+1. Cloning
+2. Credentials set up (git user.name & email)
+3. Signing off (DCO)
+-->

documentation/project/contributing/software-required.md

@@ -0,0 +1,32 @@
+### Get the required software for Linux or macOS
+
+This page explains how to get the software you need to use a Linux or macOS
+machine for local development. Before you begin contributing you must have:
+
+* a GitHub account
+* Java 13 or newer
+* `git`
+* `docker`
+
+### Installing prerequisites on macOS
+1. Install [brew](https://brew.sh/).
+
+2. Install brew cask:
+```sh
+> brew cask
+``` 
+3Install JDK 13 via Homebrew cask:
+```sh
+> brew tap adoptopenjdk/openjdk
+> brew install adoptopenjdk13
+```
+
+## Tips
+
+Consider allocating not less than 4GB of memory for your docker. 
+Otherwise, some apps within a stack (e.g. `kafka-ui.yaml`) might crash.
+
+## Where to go next
+
+In the next section, you'll [learn how to build the application](building.md).
+### GIT SETUP

documentation/project/contributing/testing.md

@@ -0,0 +1,28 @@
+# Testing
+
+
+
+## Test suites
+
+
+## Writing new tests
+
+
+### Writing tests for new features
+
+
+### Writing tests for bug fixes
+
+
+### Writing new integration tests
+
+
+
+## Running tests
+
+### Unit Tests
+
+
+### Integration Tests
+
+