Skip to content

Latest commit

 

History

History
200 lines (158 loc) · 13 KB

CONTRIBUTING.md

File metadata and controls

200 lines (158 loc) · 13 KB
Raw

First off, thanks for taking the time to contribute! 💪🐘🎉

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:

These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Table of contents

Code of conduct

This project and everyone participating in it are governed by the Database Lab Engine Community Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to community@postgres.ai.

Contributor Covenant

TL;DR – I just have a question, where to ask it?

Note: Please don't open an issue to just ask a question. You will get faster results by using the channels below.

How can I contribute?

Reporting bugs

  • Use a clear and descriptive title for the issue to identify the problem.
  • Make sure you test against the latest released version. We may have already fixed the bug you're experiencing.
  • 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).
  • Explain which behavior you expected to see instead and why.
  • Please include DLE logs. Include Postgres logs from clones and/or the sync container's Postgres, if relevant.
  • Describe DLE configuration: mode you are using (physical or logical), other details of DLE configuration, Postgres configuration snippets.
  • 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.
  • Check if you have sensitive information in the logs and configs and remove any.
  • You can submit a bug report in either GitLab Issues or GitHub Issues sections – both places are monitored.
  • 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.
  • If you need to report a security issue, follow instructions in "Database Lab Engine security guidelines".

Proposing enhancements

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.

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.

Enhancement suggestions are tracked on GitLab or GitHub. Recommendations:

  • Use a clear and descriptive title for the issue to identify the suggestion.
  • Provide a step-by-step description of the proposed enhancement in as many details as possible.
  • Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples
  • Use Markdown to format code snippets and improve the overall look of your issues (Markdown docs: GitLab, GitHub).
  • Describe the current behavior and explain which behavior you expected to see instead and why (on GitLab, you can use the issue template, which is selected by default).
  • 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.
  • Explain why this proposal would be helpful to most DLE users.
  • Specify which version of DLE you're using. If it makes sense, specify Postgres versions too.
  • Specify the name and version of the OS you're using.

Your first code contribution

We appreciate first-time contributors, and we are happy to assist you in getting started. In case of any questions, reach out to us!

You find some issues that are considered as good for first-time contributors looking at the issues with the good-first-issue label. 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.

Translation

We are translating README.md, CONTRIBUTING.md (this document), and other documents in the repository to various languages to make Database Lab Engine more accessible around the globe. Help in this area is always appreciated. You can start from translating the project's README to your native language and save it in ./translations/README.{language}.md. You can find examples in the ./translations directory

Roadmap

There is the Roadmap section 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.

Merge Requests / Pull Requests

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.

Please follow these steps to have your contribution considered by the maintainers:

  1. Follow the styleguides.
  2. Provide a detailed description of your MR/PR following the same rules as you would use for opening an issue (see Reporting Bugs and Proposing Enhancements above).
  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. Download it, fill out the fields, sign, and send to contribute@postgres.ai.

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.

Note: You would need to have a verified GitLab account to run CI/CD pipelines required to merge the MR/PR. Please, keep your fork repository public for the same reasons.

Additional materials that are worth checking out:

Styleguides

Git commit messages

Go styleguide

We encourage you to follow the principles described in the following documents:

Documentation styleguide

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.

We're building documentation following the principles described at https://documentation.divio.com/:

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.

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.

Learn more: https://documentation.divio.com/.

Repo overview

The postgres-ai/database-lab repo contains 2 components:

Components have a separate version, denoted by either:

  • a certain type of the git tag (for example, v0.0.0 for Database Lab Engine, and ui0.0.0 for Database Lab UI) or
  • a combination of the branch name and git commit SHA.

Development setup

  • Install Docker. Example for Linux: 
    # Install dependencies
sudo apt-get update && sudo apt-get install -y \
  apt-transport-https \
  ca-certificates \
  curl \
  gnupg-agent \
  software-properties-common
# Install Docker
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

sudo add-apt-repository \
  "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) \
  stable"

sudo apt-get update && sudo apt-get install -y \
  docker-ce \
  docker-ce-cli \
  containerd.io
  • Install ZFS and create zpool. Example for Linux: 
    # Install ZFS
sudo apt-get install -y zfsutils-linux

sudo zpool create -f \
  -O compression=on \
  -O atime=off \
  -O recordsize=128k \
  -O logbias=throughput \
  -m /var/lib/dblab/dblab_pool \
  dblab_pool \
  "/dev/nvme1n1" # ! check your device or use an empty file here;
                 # empty file creation example: truncate --size 10GB ./pseudo-disk-for-zfs
  • Install golangci-lint: https://github.com/golangci/golangci-lint#install

Building from source

Use Makefile to build Database Lab components from source.

Run make help to see all available targets.