mirror of
https://github.com/open-metadata/OpenMetadata.git
synced 2025-08-29 11:26:05 +00:00
Reorganize docs (#2495)
* Reorganize docs * Move UX Style guide to parent directory
This commit is contained in:
Matt
GitHub
parent
f6ac393007
commit
a82952f5d9
@ -128,8 +128,10 @@
|
||||
## Open Source Community
|
||||
|
||||
* [Community](open-source-community/community.md)
|
||||
* [UX Style Guide](open-source-community/ux-style-guide.md)
|
||||
* [Developer](open-source-community/developer/README.md)
|
||||
* [How to Contribute](open-source-community/developer/how-to-contribute.md)
|
||||
* [Prerequisites](open-source-community/developer/prerequisites.md)
|
||||
* [Backend](open-source-community/developer/backend/README.md)
|
||||
* [Build the code & run tests](open-source-community/developer/build-code-run-tests.md)
|
||||
* [Quick Start Guide](open-source-community/developer/quick-start-guide.md)
|
||||
@ -140,9 +142,7 @@
|
||||
* [Stage](open-source-community/developer/build-a-connector/stage.md)
|
||||
* [BulkSink](open-source-community/developer/build-a-connector/bulksink.md)
|
||||
* [Run Integration Tests](open-source-community/developer/run-integration-tests.md)
|
||||
* [UX Style Guide](open-source-community/developer/ux-style-guide.md)
|
||||
* [Generate Typescript Types From JSON Schema](open-source-community/developer/generate-typescript-types-from-json-schema.md)
|
||||
* [Run OpenMetadata UI Locally](open-source-community/developer/run-openmetadata-ui-locally.md)
|
||||
* [UI](docs/open-source-community/developer/ui/README.md)
|
||||
* [Solution Design](open-source-community/developer/solution-design.md)
|
||||
* [Python API](open-source-community/developer/python-api.md)
|
||||
* [Entities](open-source-community/developer/entities/README.md)
|
||||
|
||||
@ -6,6 +6,18 @@ This document summarizes information relevant to OpenMetadata committers and con
|
||||
[how-to-contribute.md](how-to-contribute.md)
|
||||
{% endcontent-ref %}
|
||||
|
||||
{% content-ref url="ux-style-guide.md" %}
|
||||
[ux-style-guide.md](docs/open-source-community/ux-style-guide.md)
|
||||
{% endcontent-ref %}
|
||||
|
||||
{% content-ref url="prerequisites.md" %}
|
||||
[prerequisites.md](prerequisites.md)
|
||||
{% endcontent-ref %}
|
||||
|
||||
{% content-ref url="backend/" %}
|
||||
[backend](backend/)
|
||||
{% endcontent-ref %}
|
||||
|
||||
{% content-ref url="build-code-run-tests.md" %}
|
||||
[build-code-run-tests.md](build-code-run-tests.md)
|
||||
{% endcontent-ref %}
|
||||
@ -22,12 +34,8 @@ This document summarizes information relevant to OpenMetadata committers and con
|
||||
[run-integration-tests.md](run-integration-tests.md)
|
||||
{% endcontent-ref %}
|
||||
|
||||
{% content-ref url="ux-style-guide.md" %}
|
||||
[ux-style-guide.md](ux-style-guide.md)
|
||||
{% endcontent-ref %}
|
||||
|
||||
{% content-ref url="generate-typescript-types-from-json-schema.md" %}
|
||||
[generate-typescript-types-from-json-schema.md](generate-typescript-types-from-json-schema.md)
|
||||
{% content-ref url="ui/" %}
|
||||
[ui](ui/)
|
||||
{% endcontent-ref %}
|
||||
|
||||
{% content-ref url="solution-design.md" %}
|
||||
|
||||
@ -1,2 +0,0 @@
|
||||
# Backend
|
||||
|
||||
@ -5,12 +5,11 @@
|
||||
1. Avoid cryptic abbreviations. Single letter variable names are fine in very short methods with few variables, otherwise, make them informative.
|
||||
2. Clear code is preferable to comments. When possible make naming so good that you don't need comments. When that isn't possible comments should be thought of as mandatory, write them to be read.
|
||||
3. Logging, configuration, and public APIs are our "UI". Make them pretty, consistent, and usable.
|
||||
4. The maximum line length is 120.
|
||||
5. Create Github issues instead of leaving `TODO`s and `FIXME`s in code.
|
||||
6. Don't leave println statements in the code.
|
||||
7. User documentation should be considered a part of any user-facing feature, just like unit tests. Eg: REST APIs should've accompanying documentation.
|
||||
8. Tests should never rely on timing in order to pass.
|
||||
9. Every unit test should leave no side effects, i.e., any test dependencies should be set during setup and cleaned during tear down.
|
||||
4. Create Github issues instead of leaving `TODO`s and `FIXME`s in code.
|
||||
5. Use logger instead of leaving print statements in the code.
|
||||
6. User documentation should be considered a part of any user-facing feature, just like unit tests. Eg: REST APIs should've accompanying documentation.
|
||||
7. Tests should never rely on timing in order to pass.
|
||||
8. Every unit test should leave no side effects, i.e., any test dependencies should be set during setup and cleaned during tear down.
|
||||
|
||||
## Java
|
||||
|
||||
@ -29,7 +28,7 @@
|
||||
5. No raw types. Do not use raw generic types, unless strictly necessary (sometimes necessary for signature matches, arrays).
|
||||
6. Suppress warnings. Add annotations to suppress warnings, if they cannot be avoided (such as “unchecked”, or “serial”).
|
||||
7. Comments. Add JavaDocs to public methods or inherit them by not adding any comments to the methods.
|
||||
8. Logger instance should be upper case LOG.
|
||||
8. Use @Slf4j annotation to instantiate the logger.
|
||||
9. When in doubt refer to existing code or [Java Coding Style](http://google.github.io/styleguide/javaguide.html) except line breaking, which is described above.
|
||||
|
||||
## Logging
|
||||
|
||||
@ -9,7 +9,7 @@ For learning advanced debugging skills with IntellJ, please refer IntelliJ's off
|
||||
|
||||
Identify the statements of interest in the codebase and set up breakpoints, by clicking on the left margin (red dot indicates a break point).
|
||||
|
||||
|
||||
|
||||
|
||||
You may add more breakpoints while the debugger is running.
|
||||
|
||||
@ -17,22 +17,22 @@ You may add more breakpoints while the debugger is running.
|
||||
|
||||
Start the OpenMetadata CatalogApplication in Debug mode from the Run menu.
|
||||
|
||||
|
||||
|
||||
|
||||
Check the bottom panel to ensure that the Debugger started successfully.
|
||||
|
||||
|
||||
|
||||
|
||||
## Inspect the Codebase
|
||||
|
||||
Invoke the statement of interest through a preferable methodology (running unit test or through actual API call).
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
The debugger will pause execution as it encounters a breakpoint.
|
||||
Use the Step actions as needed to step through the codebase.
|
||||
Inspect variables in the variables tab to see if they have the expected values.
|
||||
|
||||
|
||||
|
||||
|
||||
@ -2,7 +2,6 @@
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* Make sure you are using maven 3.5.x or higher and JDK 11 or higher.
|
||||
* Make sure you have a local instance of MySQL and ElasticSearch.
|
||||
|
||||
* For an easy install of MySQL and ES, just install Docker on your local machine and run the following commands from the top-level directory
|
||||
|
||||
49
docs/open-source-community/developer/prerequisites.md
Normal file
49
docs/open-source-community/developer/prerequisites.md
Normal file
@ -0,0 +1,49 @@
|
||||
---
|
||||
description: This guide will help you set up all prerequisites to develop on OpenMetadata.
|
||||
---
|
||||
|
||||
OpenMetadata being a full stack project, we use the following for development:
|
||||
|
||||
- [Docker 20 or higher](https://docs.docker.com/engine/install/)
|
||||
- [Java JDK 11 or higher](https://docs.oracle.com/en/java/javase/17/install/overview-jdk-installation.html)
|
||||
- [Maven 3.5.x or higher](https://maven.apache.org/install.html)
|
||||
- [Python 3.7 or higher](https://www.python.org/downloads/)
|
||||
- [Node >=10.0.0](https://nodejs.org/en/download/)
|
||||
- [Yarn ^1.22.0](https://classic.yarnpkg.com/lang/en/docs/install/)
|
||||
|
||||
|
||||
Here is a snapshot of a working environment on a Macbook.
|
||||
|
||||
```
|
||||
> docker --version
|
||||
Docker version 20.10.8, build 3967b7d
|
||||
|
||||
> mvn -version
|
||||
Apache Maven 3.8.2 (ea98e05a04480131370aa0c110b8c54cf726c06f)
|
||||
Maven home: /usr/local/Cellar/maven/3.8.2/libexec
|
||||
Java version: 11.0.11, vendor: AdoptOpenJDK, runtime: /Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk/Contents/Home
|
||||
Default locale: en_US, platform encoding: UTF-8
|
||||
OS name: "mac os x", version: "10.15.7", arch: "x86_64", family: "mac"
|
||||
|
||||
> java -version
|
||||
openjdk version "11.0.11" 2021-04-20
|
||||
OpenJDK Runtime Environment AdoptOpenJDK-11.0.11+9 (build 11.0.11+9)
|
||||
OpenJDK 64-Bit Server VM AdoptOpenJDK-11.0.11+9 (build 11.0.11+9, mixed mode)
|
||||
|
||||
> make -version
|
||||
GNU Make 3.81
|
||||
Copyright (C) 2006 Free Software Foundation, Inc.
|
||||
This is free software; see the source for copying conditions.
|
||||
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
|
||||
PARTICULAR PURPOSE.
|
||||
|
||||
This program built for i386-apple-darwin11.3.0
|
||||
> python --version
|
||||
Python 3.9.9
|
||||
|
||||
> node --version
|
||||
v17.3.0
|
||||
|
||||
> yarn --version
|
||||
1.22.17
|
||||
```
|
||||
19
docs/open-source-community/developer/ui/README.md
Normal file
19
docs/open-source-community/developer/ui/README.md
Normal file
@ -0,0 +1,19 @@
|
||||
---
|
||||
description: Documentation to get you upto speed on building, running and testing UI for OpenMetadata
|
||||
---
|
||||
|
||||
# UI (Typescript)
|
||||
|
||||
We use Typescript and React for developing OpenMetadata UI. Following are the key technologies that we use for the backend:
|
||||
|
||||
- [typescript](https://www.typescriptlang.org/) for Javascript with typed syntax
|
||||
- [ReactJS](https://reactjs.org/)
|
||||
|
||||
|
||||
{% content-ref url="generating-types.md" %}
|
||||
[generating-types.md](generating-types.md)
|
||||
{% endcontent-ref %}
|
||||
|
||||
{% content-ref url="run-locally.md" %}
|
||||
[run-locally.md](run-locally.md)
|
||||
{% endcontent-ref %}
|
||||
@ -6,16 +6,6 @@ description: This guide will help you to run OpenMetadata UI locally.
|
||||
|
||||
### **Pre-requisites**
|
||||
|
||||
Before proceeding, ensure that you have installed the node and yarn with the versions given below.
|
||||
|
||||
```
|
||||
"node": ">=10.0.0",
|
||||
"yarn": "^1.22.0"
|
||||
```
|
||||
|
||||
[**Install Node**](https://nodejs.org/en/download/)\
|
||||
[**Install Yarn**](https://classic.yarnpkg.com/lang/en/docs/install/)****
|
||||
|
||||
Using the command below, spin up the server locally from the directory.`openmetadata-dist/target/openmetadata-*-SNAPSHOT`.
|
||||
|
||||
```shell
|
||||
@ -1,10 +0,0 @@
|
||||
# UX Style Guide
|
||||
|
||||
The purpose of a style guide is to make sure that multiple contributors create in a clear and cohesive way that ensures style consistency with everything from design to writing.
|
||||
|
||||
[Click here](https://www.figma.com/file/sw3NcGyvATuwL4l7astZXL/OpenMetadata-Style-Guide) to see the Figma design.
|
||||
|
||||
{% file src="../../.gitbook/assets/openmetadata-style-guide.pdf" caption="OpenMetadata Style Guide" %}
|
||||
|
||||
|
||||
|
||||
11
docs/open-source-community/ux-style-guide.md
Normal file
11
docs/open-source-community/ux-style-guide.md
Normal file
@ -0,0 +1,11 @@
|
||||
# UX Style Guide
|
||||
|
||||
We have a UX style guide to ensure OpenMetadata UI to be designed and developed in a clear and cohesive way for consistency throughout the project.
|
||||
|
||||
|
||||
|
||||
[Click here](https://www.figma.com/file/sw3NcGyvATuwL4l7astZXL/OpenMetadata-Style-Guide) to see the Figma design.
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user