Skip to content

Commit 044bd63

Browse files
NikolaySNikolayS
committed
Merge branch 'rework-readme' into 'master'
Rework README See merge request postgres-ai/database-lab!411
2 parents 0421f14 + 25c8cd6 commit 044bd63

11 files changed

+566
-57
lines changed

‎.gitlab-ci.yml

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ include:
55

66
variables:
77
SAST_EXCLUDED_ANALYZERS: "semgrep-sast"
8+
DOCKER_DRIVER: overlay2
89

910
stages:
1011
- test

‎CODE_OF_CONDUCT.md

+130
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Database Lab Engine Community Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, caste, color, religion, or sexual identity
10+
and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment for our
18+
community include:
19+
20+
* Demonstrating empathy and kindness toward other people
21+
* Being respectful of differing opinions, viewpoints, and experiences
22+
* Giving and gracefully accepting constructive feedback
23+
* Accepting responsibility and apologizing to those affected by our mistakes,
24+
and learning from the experience
25+
* Focusing on what is best not just for us as individuals, but for the
26+
overall community
27+
28+
Examples of unacceptable behavior include:
29+
30+
* The use of sexualized language or imagery, and sexual attention or
31+
advances of any kind
32+
* Trolling, insulting or derogatory comments, and personal or political attacks
33+
* Public or private harassment
34+
* Publishing others' private information, such as a physical or email
35+
address, without their explicit permission
36+
* Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
## Enforcement Responsibilities
40+
41+
Community leaders are responsible for clarifying and enforcing our standards of
42+
acceptable behavior and will take appropriate and fair corrective action in
43+
response to any behavior that they deem inappropriate, threatening, offensive,
44+
or harmful.
45+
46+
Community leaders have the right and responsibility to remove, edit, or reject
47+
comments, commits, code, wiki edits, issues, and other contributions that are
48+
not aligned to this Code of Conduct, and will communicate reasons for moderation
49+
decisions when appropriate.
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all community spaces, and also applies when
54+
an individual is officially representing the community in public spaces.
55+
Examples of representing our community include using an official e-mail address,
56+
posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event.
58+
59+
## Enforcement
60+
61+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
62+
reported to the community leaders responsible for enforcement at
63+
*[email protected]*.
64+
All complaints will be reviewed and investigated promptly and fairly.
65+
66+
All community leaders are obligated to respect the privacy and security of the
67+
reporter of any incident.
68+
69+
## Enforcement Guidelines
70+
71+
Community leaders will follow these Community Impact Guidelines in determining
72+
the consequences for any action they deem in violation of this Code of Conduct:
73+
74+
### 1. Correction
75+
76+
**Community Impact**: Use of inappropriate language or other behavior deemed
77+
unprofessional or unwelcome in the community.
78+
79+
**Consequence**: A private, written warning from community leaders, providing
80+
clarity around the nature of the violation and an explanation of why the
81+
behavior was inappropriate. A public apology may be requested.
82+
83+
### 2. Warning
84+
85+
**Community Impact**: A violation through a single incident or series
86+
of actions.
87+
88+
**Consequence**: A warning with consequences for continued behavior. No
89+
interaction with the people involved, including unsolicited interaction with
90+
those enforcing the Code of Conduct, for a specified period of time. This
91+
includes avoiding interactions in community spaces as well as external channels
92+
like social media. Violating these terms may lead to a temporary or
93+
permanent ban.
94+
95+
### 3. Temporary Ban
96+
97+
**Community Impact**: A serious violation of community standards, including
98+
sustained inappropriate behavior.
99+
100+
**Consequence**: A temporary ban from any sort of interaction or public
101+
communication with the community for a specified period of time. No public or
102+
private interaction with the people involved, including unsolicited interaction
103+
with those enforcing the Code of Conduct, is allowed during this period.
104+
Violating these terms may lead to a permanent ban.
105+
106+
### 4. Permanent Ban
107+
108+
**Community Impact**: Demonstrating a pattern of violation of community
109+
standards, including sustained inappropriate behavior, harassment of an
110+
individual, or aggression toward or disparagement of classes of individuals.
111+
112+
**Consequence**: A permanent ban from any sort of public interaction within
113+
the community.
114+
115+
## Attribution
116+
117+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118+
version 2.1, available at [v2.1].
119+
120+
Community Impact Guidelines were inspired by [Mozilla CoC].
121+
122+
For answers to common questions about this code of conduct, see the FAQ at
123+
[FAQ]. Translations are available
124+
at [translations].
125+
126+
[homepage]: https://www.contributor-covenant.org
127+
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
128+
[Mozilla CoC]: https://github.com/mozilla/diversity
129+
[FAQ]: https://www.contributor-covenant.org/faq
130+
[translations]: https://www.contributor-covenant.org/translations

‎CONTRIBUTING.md

+182
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
First off, thanks for taking the time to contribute! 💪🐘🎉
2+
3+
The following is a set of guidelines for contributing to Database Lab Engine (DLE) and its additional components, which are hosted on GitLab and GitHub:
4+
- https://gitlab.com/postgres-ai/database-lab
5+
- https://github.com/postgres-ai/database-lab-engine
6+
7+
These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
8+
9+
---
10+
11+
#### Table of contents
12+
13+
- [Code of conduct](#code-of-conduct)
14+
- [TL;DR – I just have a question, where to ask it?](#tldr-i-just-have-a-question-where-to-ask-it)
15+
- [How can I contribute?](#how-can-i-contribute)
16+
- [Reporting bugs](#reporting-bugs)
17+
- [Proposing enhancements](#proposing-enhancements)
18+
- [Your first code contribution](#your-first-code-contribution)
19+
- [Roadmap](#roadmap)
20+
- [Merge Requests / Pull Requests](#merge-requests-pull-requests)
21+
- [Development guides](#repo-overview)
22+
- [Git commit messages](#git-commit-messages)
23+
- [Go styleguide](#go-styleguide)
24+
- [Documentation styleguide](#documentation-styleguide)
25+
- [Development setup](#development-setup)
26+
<!--
27+
- [Repo overview](#repo-overview)
28+
- [Building from source](#building-from-source)
29+
-->
30+
31+
---
32+
33+
## Code of conduct
34+
This project and everyone participating in it are governed by the [Database Lab Engine Community Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [[email protected]](mailto:[email protected]).
35+
36+
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](./CODE_OF_CONDUCT.md)
37+
38+
## TL;DR – I just have a question, where to ask it?
39+
40+
> **Note:** Please don't open an issue to just ask a question. You will get faster results by using the channels below.
41+
42+
- Fast ways to get in touch: [Contact page](https://postgres.ai/contact)
43+
- [Database Lab Community Slack](https://slack.postgres.ai) (English)
44+
- [Telegram](https://t.me/databaselabru) (Russian)
45+
46+
## How can I contribute?
47+
### Reporting bugs
48+
- Use a clear and descriptive title for the issue to identify the problem.
49+
- Make sure you test against the latest released version. We may have already fixed the bug you're experiencing.
50+
- Provide steps to reproduce the issue, including DLE version, PostgreSQL version, and the platform you are running on (some examples: RDS, self-managed Postgres on an EC2 instance, self-managed Postgres on-prem).
51+
- Explain which behavior you expected to see instead and why.
52+
- Please include DLE logs. Include Postgres logs from clones and/or the sync container's Postgres, if relevant.
53+
- Describe DLE configuration: mode you are using (physical or logical), other details of DLE configuration, Postgres configuration snippets.
54+
- If the issue is related to UI, include screenshots and animated GIFs. Please, do NOT use screenshots for console output, configs, and logs – for those, always prefer the textual form.
55+
- Check if you have sensitive information in the logs and configs and remove any.
56+
- You can submit a bug report in either [GitLab Issues](https://gitlab.com/postgres-ai/database-lab) or [GitHub Issues](https://github.com/postgres-ai/database-lab-engine) sections – both places are monitored.
57+
- If you believe that there is an urgency related to the reported bug, feel free to reach out to the project maintainers. Additionally, using one of [the channels described above](#tldr-i-just-have-a-question-where-to-ask-it).
58+
- If you need to report a security issue, follow instructions in ["Database Lab Engine security guidelines"](./SECURITY.md).
59+
60+
### Proposing enhancements
61+
This section guides you through submitting an enhancement suggestion for DLE, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related proposals.
62+
63+
When you are creating an enhancement suggestion, please include as many details as possible. Include the steps that you imagine you would take if the feature you're requesting existed.
64+
65+
Enhancement suggestions are tracked on [GitLab](https://gitlab.com/postgres-ai/database-lab) or [GitHub](https://github.com/postgres-ai/database-lab-engine). Recommendations:
66+
67+
- Use a clear and descriptive title for the issue to identify the suggestion.
68+
- Provide a step-by-step description of the proposed enhancement in as many details as possible.
69+
- Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples
70+
- Use Markdown to format code snippets and improve the overall look of your issues (Markdown docs: [GitLab](https://docs.gitlab.com/ee/user/markdown.html), [GitHub](https://github.github.com/gfm/)).
71+
- Describe the current behavior and explain which behavior you expected to see instead and why.
72+
- If your proposal is related to UI, include screenshots and animated GIFs which help you demonstrate the steps or point out the part of DLE to which the suggestion is related. Please, do NOT use screenshots for console output, logs, configs.
73+
- Explain why this proposal would be helpful to most DLE users.
74+
- Specify which version of DLE you're using. If it makes sense, specify Postgres versions too.
75+
- Specify the name and version of the OS you're using.
76+
77+
### Your first code contribution
78+
We appreciate first-time contributors, and we are happy to assist you in getting started. In case of any questions, reach out to us!
79+
80+
You find some issues that are considered as good for first-time contributors looking at [the issues with the `good-first-issue` label](https://gitlab.com/postgres-ai/database-lab/-/issues?label_name%5B%5D=good+first+issue). Assign yourself to an issue and start discussing a possible solution. It is always a good idea to discuss and collaborate before you propose an MR/PR.
81+
82+
### Roadmap
83+
There is [the Roadmap section](https://postgres.ai/docs/roadmap) in the docs. It contains some major items defining big goals for the development team and the DLE community. However, these items cannot be considered a strict plan, so there are no guarantees that everything from the list will be necessarily implemented.
84+
85+
### Merge Requests / Pull Requests
86+
DLE is developed on GitLab, so MRs (merge requests) there is a way to propose a contribution. GitHub PRs (pull requests) are also an option but note that eventually, the proposal will need to be moved to GitLab, so the processing time may be increased.
87+
88+
Please follow these steps to have your contribution considered by the maintainers:
89+
1. Follow the [styleguides](#styleguides).
90+
2. Provide a detailed description of your MR/PR following the same rules as you would use for opening an issue (see [Reporting Bugs](#reporting-bugs) and [Proposing Enhancements](#proposing-enhancements) above).
91+
3. To get your MR/PR merged, you will need to sign Postgres.ai Database Lab Engine Contributor Agreement and ensure that the Postgres.ai team has received it. The template can be found here: [DLE-CA](https://bit.ly/dle-ca). Download it, fill out the fields, sign, and send to [email protected].
92+
93+
While the prerequisites above must be satisfied before having your MR/PR reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your MR/PR can be ultimately accepted.
94+
95+
Additional materials that are worth checking out:
96+
- [Git-related guidelines in the PostgreSQL project](https://wiki.postgresql.org/wiki/Working_with_Git)
97+
- [GitLab flow](https://docs.gitlab.com/ee/topics/gitlab_flow.html)
98+
99+
## Styleguides
100+
### Git commit messages
101+
- Think about other people: how likely will they understand you?
102+
- Use the present tense ("Add feature" not "Added feature")
103+
- Use the imperative mood ("Create clone..." not "Creates clone...")
104+
- Limit the first line to 72 characters or less
105+
- Reference issues and MRs/PRs liberally after the first line
106+
- Below the first line, add a detailed description of the commit. The more details the commit message has, the better. PostgreSQL project has a good culture of writing very informative commit messages – [check out a few of them](https://git.postgresql.org/gitweb/?p=postgresql.git;a=summary) to get inspired.
107+
- Read this: ["How to write a good commit message"](https://docs.gitlab.com/ee/topics/gitlab_flow.html#how-to-write-a-good-commit-message)
108+
- All Git commits must be signed. Unsigned commits are rejected.
109+
- [How to sign a commit](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)
110+
- [How to sign what already committed (but not yet pushed)](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)
111+
- [GitLab-specific guidelines](https://docs.gitlab.com/ee/user/project/repository/gpg_signed_commits/)
112+
113+
### Go styleguide
114+
We encourage you to follow the principles described in the following documents:
115+
- [Effective Go](https://go.dev/doc/effective_go)
116+
- [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
117+
118+
### Documentation styleguide
119+
Documentation for Database Lab Engine and additional components is hosted at https://postgres.ai/docs and is maintained in this GitLab repo: https://gitlab.com/postgres-ai/docs.
120+
121+
We're building documentation following the principles described at https://documentation.divio.com/:
122+
123+
> There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four.
124+
>
125+
> They are: tutorials, how-to guides, technical reference and explanation. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most documentation - often immensely.
126+
127+
Learn more: https://documentation.divio.com/.
128+
129+
<!--
130+
### Repo overview
131+
TBD
132+
-->
133+
134+
### Development setup
135+
- Install Docker. Example for Linux:
136+
```bash
137+
# Install dependencies
138+
sudo apt-get update && sudo apt-get install -y \
139+
apt-transport-https \
140+
ca-certificates \
141+
curl \
142+
gnupg-agent \
143+
software-properties-common
144+
# Install Docker
145+
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
146+
147+
sudo add-apt-repository \
148+
"deb [arch=amd64] https://download.docker.com/linux/ubuntu \
149+
$(lsb_release -cs) \
150+
stable"
151+
152+
sudo apt-get update && sudo apt-get install -y \
153+
docker-ce \
154+
docker-ce-cli \
155+
containerd.io
156+
```
157+
- Install ZFS and create zpool. Example for Linux:
158+
```bash
159+
# Install ZFS
160+
sudo apt-get install -y zfsutils-linux
161+
162+
sudo zpool create -f \
163+
-O compression=on \
164+
-O atime=off \
165+
-O recordsize=128k \
166+
-O logbias=throughput \
167+
-m /var/lib/dblab/dblab_pool \
168+
dblab_pool \
169+
"/dev/nvme1n1" # ! check your device or use an empty file here;
170+
# empty file creation example: truncate --size 10GB ./pseudo-disk-for-zfs
171+
```
172+
- Install `golangci-lint`: https://github.com/golangci/golangci-lint#install
173+
174+
<!-- TODO: Linux specific requirements? MacOS specific? -->
175+
176+
<!--
177+
### Building from source
178+
TBD – separately for Linux and MacOS
179+
180+
181+
mention dev images: See our [GitLab Container Registry](https://gitlab.com/postgres-ai/database-lab/container_registry) to find the images built for development branches.
182+
-->

0 commit comments

Comments
 (0)