Dev in GitHub

12 files changed, 368 insertions, 55 deletions

diff --git a/ydb/docs/en/core/development/build-ya.md b/ydb/docs/en/core/development/build-ya.md
new file mode 100644
index 00000000000..813bcb7ac27
--- /dev/null
+++ b/ydb/docs/en/core/development/build-ya.md
@@ -0,0 +1,94 @@
+# Build and test YDB using Ya Make
+
+**Ya Make** is a build and test system used historically for YDB development. Initially designed for C++, now it supports number of programming languages including Java, Go, and Python.
+
+**Ya Make** build configuration language is a primary one for YDB, with a `ya.make` file in each directory representing Ya Make targets.
+
+Setup the development environment as described in [Working on a change - Setup environment](suggest-change.md) arcticle to work with `Ya Make`.
+
+## Running Ya commands {#run_ya}
+
+There's a `ya` script in the YDB repository root to run `Ya Make` commands from the console. You can add it to the PATH evniromnet variable to enable launching without specifiying a full path. For Linux/Bash and GitHub repo cloned to `~/ydbwork/ydb` you can use the following command:
+
+```
+echo "alias ya='~/ydbwork/ydb/ya'" >> ~/.bashrc
+source ~/.bashrc
+```
+
+Run `ya` without parameters to get help:
+
+```
+$ ya
+Yet another build tool.
+
+Usage: ya [--precise] [--profile] [--error-file ERROR_FILE] [--keep-tmp] [--no-logs] [--no-report] [--no-tmp-dir] [--print-path] [--version] [-v] [--diag] [--help] <SUBCOMMAND> [OPTION]...
+
+Options:
+...
+
+Available subcommands:
+...
+```
+
+You can get detailed help on any subcommand launching it with a `--help` flag, for instance:
+
+```
+$ ya make --help
+Build and run tests
+To see more help use -hh/-hhh
+
+Usage:
+  ya make [OPTION]... [TARGET]...
+
+Examples:
+  ya make -r               Build current directory in release mode
+  ya make -t -j16 library  Build and test library with 16 threads
+  ya make --checkout -j0   Checkout absent directories without build
+
+Options:
+...
+```
+
+The `ya` script downloads required platform-specific artifacts when started, and caches them locally. Periodically, the script is updated with the links to the new versions of the artifacts.
+
+## Setup IDE {#ide}
+
+If you're using IDE for development, there's a command `ya ide` which helps you create a project with configured tools. The following IDEs are supported: goland, idea, pycharm, venv, vscode (multilanguage, clangd, go, py).
+
+Go to the directory in the source code which you need to be a root of your project. Run the `ya ide` command specifying the IDE name, and the target directory to write the IDE project configuration in a `-P` parameter. For instance, to work on the YQL library changes in vscode you can run the following command:
+
+```
+cd ~/ydbwork/ydb/library/yql
+ya ide vscode -P=~/ydbwork/vscode/yqllib
+```
+
+Now you can open the `~/ydbwork/vscode/yqllib/ide.code-workspace` from vscode.
+
+## Build a target {#make}
+
+There are 3 basic types of targets in `Ya Make`: Program, Test, and Library. To build a target run `ya make` with the directory name. For instance, to build a YDB CLI run:
+
+```
+cd ~/ydbwork/ydb
+ya make ydb/apps/ydb
+```
+
+You can also run `ya make` from inside a target directory without parameters:
+
+```
+cd ~/ydbwork/ydb/ydb/apps/ydb
+ya make
+```
+
+## Run tests {#test}
+
+Running a `ya test` command in some directory will build all test binaries located inside its subdirectories, and start tests.
+
+For instance, to run YDB Core small tests run:
+
+```
+cd ~/ydbwork/ydb
+ya test ydb/core
+```
+
+To run medium and large tests, add options `-tt` and `-ttt` to the `ya test` call, respectively.
\ No newline at end of file
diff --git a/ydb/docs/en/core/development/index.md b/ydb/docs/en/core/development/index.md
new file mode 100644
index 00000000000..7bcc256951d
--- /dev/null
+++ b/ydb/docs/en/core/development/index.md
@@ -0,0 +1,6 @@
+# YDB Development
+
+This section contains guidelines for YDB developers and contributors.
+
+* [Working on a change](suggest-change.md)
+* [Build and test using Ya Make build system](build-ya.md)
diff --git a/ydb/docs/en/core/development/suggest-change.md b/ydb/docs/en/core/development/suggest-change.md
new file mode 100644
index 00000000000..b6453014914
--- /dev/null
+++ b/ydb/docs/en/core/development/suggest-change.md
@@ -0,0 +1,188 @@
+# Development process: working on a change for YDB
+
+This section contains a step-by-step scenario which helps you complete necessary configuration steps, and learn how to bring a change to the YDB project. This scenario does not have to be strictly followed, you may develop your own approach based on the provided information.
+
+## Set up the environment {#envsetup}
+
+### GitHub account {#github_login}
+
+You need to have a GitHub account to suggest any changes to the YDB source code. Register at [github.com](https://github.com/) if haven't done it yet.
+
+### SSH key pair {#ssh_key_pair}
+
+Create an SSH key pair and register the public key at your GitHub account settings to be authenticated at GitHub when running commands from a command line on your development machine.
+
+Full instructions are on [this GitHub page](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key).
+
+### Git CLI {#git_cli}
+
+You need to have the `git` command-line utility installed to run commands from the console. Visit the [Downloads](https://git-scm.com/downloads) page of the official website for installation instructions.
+
+To install it under Linux/Ubuntu run:
+
+```
+sudo apt-get update
+sudo apt-get install git
+```
+
+### GitHub CLI {#gh_cli}
+
+Using GitHub CLI enables you to create Pull Requests and manage repositories from a command line. You can also use GitHub UI for such actions.
+
+Install GitHub CLI as described [at the home page](https://cli.github.com/). For Linux Ubuntu, you can go directly to [https://github.com/cli/cli/blob/trunk/docs/install_linux.md#debian-ubuntu-linux-raspberry-pi-os-apt](https://github.com/cli/cli/blob/trunk/docs/install_linux.md#debian-ubuntu-linux-raspberry-pi-os-apt).
+
+Run authentication configuration:
+
+```
+gh auth login
+```
+You will be asked several questions interactively, answer them as follows:
+
+|Question|Answer|
+|--|--|
+|What account do you want to log into?|**GitHub.com**|
+|What is your preferred protocol for Git operations?|**SSH**|
+|Upload your SSH public key to your GitHub account?|Choose a file with a public key (extention `.pub`) of those created on the ["Create SSH key pair"](#ssh_key_pair) step, for instance **/home/user/.ssh/id_ed25519.pub**|
+|Title for your SSH key|**GitHub CLI** (leave default)|
+|How would you like to authenticate GitHub CLI|**Paste your authentication token**|
+
+After the last answer, you will be asked for a token which you can generate in the GitHub UI:
+
+```
+Tip: you can generate a Personal Access Token here https://github.com/settings/tokens
+The minimum required scopes are 'repo', 'read:org', 'admin:public_key'.
+? Paste your authentication token:
+```
+
+As advised in the "Tip:", open the [https://github.com/settings/tokens](https://github.com/settings/tokens), click on "Generate new token" / "Classic", tick three boxes "repo", "admin:public_key" and "read:org" (under "admin:org"), and copy-paste the shown token to complete the GitHub CLI configuration.
+
+### Fork and clone repository {#fork_create}
+
+YDB official repository is [https://github.com/ydb-platform/ydb](https://github.com/ydb-platform/ydb), located under the YDB organization account `ydb-platform`.
+
+To work on the YDB code changes, you need to create a fork repository under your GitHub account, and clone it locally. There's a single GitHub CLI command which does all of that together:
+
+```
+mkdir -p ~/ydbwork
+cd ~/ydbwork
+```
+```
+gh repo fork ydb-platform/ydb --default-branch-only --clone
+```
+
+Once completed, you have a YDB Git repository fork cloned to `~/ydbwork/ydb`.
+
+Forking a repository is an instant action, however cloning to the local machine takes some time to transfer about 650 MB of repository data over the network.
+
+### Configure commit authorship {#author}
+
+Run the following command from your repository directory to set up your name and email for commits pushed using Git:
+
+```
+cd ~/ydbwork/ydb
+```
+```
+git config --global user.name "Marco Polo"
+git config --global user.email "marco@ydb.tech"
+```
+
+## Working on a feature {#feature}
+
+To start working on a feature, ensure the steps specified in the [Setup the environment](#envsetup) section above are completed.
+
+### Refresh trunk {#fork_sync}
+
+Usually you need a fresh trunk revision to branch from. Sync fork to obtain it, running the following command:
+
+```
+gh repo sync your_github_login/ydb -s ydb-platform/ydb
+```
+
+This statement performs sync remotely on GitHub. Pull the changes to the local repository then:
+
+```
+cd ~/ydbwork/ydb
+```
+```
+git checkout main
+git pull
+```
+
+### Create a development branch {#fork_sync}
+
+Create a development branch using Git (replace "feature42" with your branch name), and assign upstream for it:
+
+```
+git checkout -b feature42
+git push --set-upstream origin feature42
+```
+
+### Make changes and commits {#commit}
+
+Edit files locally, use standard Git commands to add files, verify status, make commits, and push changes to your fork repository:
+
+```
+git add .
+```
+
+```
+git status
+```
+
+```
+git commit -m "Implemented feature 42"
+```
+
+```
+git push
+```
+
+### Create a pull request to the official repository {#create_pr}
+
+When the changes are completed and locally tested (see [Ya Build and Test](build-ya.md)), run the following command from your repository root to submit a Pull Request to the YDB official repository:
+
+```
+cd ~/ydbwork/ydb
+```
+```
+gh pr create --title "Feature 42 implemented"
+```
+
+After answering some questions, the Pull Request will be created and you will get a link to its page on GitHub.com.
+
+### Precommit checks {#precommit_checks}
+
+Prior to merging, the precommit checks are run for the Pull Request. You can see its status on the Pull Request page.
+
+As part of the precommit checks, the YDB CI builds artifacts and runs all the tests, providing the results as a comment to the Pull Request.
+
+If you are not a member of the YDB team, build/test checks do not run until a team member reviews your changes and approves the PR for tests by assigning a label 'Ok-to-test'.
+
+### Test results {#test-results}
+
+You can click on the test amounts in different sections of the test results comment to get to the simple HTML test report. In this report you can see which tests have been failed/passed, and get to their logs.
+
+### Test history {#test_history}
+
+Each time when tests are run by the YDB CI, their results are uploaded to the [test history application](https://nebius.testmo.net/projects/view/1). There's a link "Test history" in the comment with test results heading to the page with the relevant run in this application.
+
+In the "Test History" YDB team members can browse test runs, search for tests, see the logs, and compare them between different test runs. If some test is failed in a particular precommit check, it can be seen in its history if this failure had been introduced by the change, or the test had been broken/flaky earlier.
+
+### Review and merge {#review}
+
+The Pull Request can be merged after obtaining an approval from the YDB team member. Comments are used for communication. Finally a reviewer from the YDB team clicks on the 'Merge' button.
+
+### Update changes {#update}
+
+If there's a Pull Request opened for some development branch in your repository, it will update every time you push to that branch, restarting the checks.
+
+### Rebase changes {#rebase}
+
+If you have conflicts on the Pull Request, you may rebase your changes on top of the actual trunk from the official repository. To do so, [refresh trunk](#fork_sync) in your fork, pull the `main` branch state to the local machine, and run the rebase command:
+
+```
+# Assuming your active branch is your development branch
+gh repo sync your_github_login/ydb -s ydb-platform/ydb
+git pull main
+git rebase main
+```
diff --git a/ydb/docs/en/core/development/toc_i.yaml b/ydb/docs/en/core/development/toc_i.yaml
new file mode 100644
index 00000000000..cc1372b19a9
--- /dev/null
+++ b/ydb/docs/en/core/development/toc_i.yaml
@@ -0,0 +1,29 @@
+items:
+- name: Working on a change
+  href: suggest-change.md
+- name: Ya Make build system
+  href: build-ya.md
+- name: Core
+  items:
+  - name: Testing with load actors
+    items:
+    - name: Overview
+      href: load-actors-overview.md
+    - name: KqpLoad
+      href: load-actors-kqp.md
+    - name: KeyValueLoad
+      href: load-actors-key-value.md
+    - name: StorageLoad
+      href: load-actors-storage.md
+    - name: VDiskLoad
+      href: load-actors-vdisk.md
+    - name: PDiskWriteLoad
+      href: load-actors-pdisk-write.md
+    - name: PDiskReadLoad
+      href: load-actors-pdisk-read.md
+    - name: PDiskLogLoad
+      href: load-actors-pdisk-log.md
+    - name: MemoryLoad
+      href: load-actors-memory.md
+    - name: Stop
+      href: load-actors-stop.md
diff --git a/ydb/docs/en/core/development/toc_p.yaml b/ydb/docs/en/core/development/toc_p.yaml
new file mode 100644
index 00000000000..94ce1108684
--- /dev/null
+++ b/ydb/docs/en/core/development/toc_p.yaml
@@ -0,0 +1,4 @@
+items:
+- name: Overview
+  href: index.md
+- include: { mode: link, path: toc_i.yaml }
\ No newline at end of file
diff --git a/ydb/docs/en/core/toc_i.yaml b/ydb/docs/en/core/toc_i.yaml
index 76260b5bff9..d6a91f4a8b3 100644
--- a/ydb/docs/en/core/toc_i.yaml
+++ b/ydb/docs/en/core/toc_i.yaml
@@ -23,34 +23,7 @@ items:
 - { name: Compatibility with PostgreSQL,                   include: { mode: link, path: postgresql/toc_p.yaml } }
 - { name: Working with the YDB CLI,                        include: { mode: link, path: reference/ydb-cli/toc_p.yaml } }
 - { name: Working with the YDB SDK,                        include: { mode: link, path: reference/ydb-sdk/toc_p.yaml } }
-- name: Development
-  # hidden: true
-  items:
-  - name: Core
-    items:
-    - name: Testing with load actors
-      items:
-      - name: Overview
-        href: development/load-actors-overview.md
-      - name: KqpLoad
-        href: development/load-actors-kqp.md
-      - name: KeyValueLoad
-        href: development/load-actors-key-value.md
-      - name: StorageLoad
-        href: development/load-actors-storage.md
-      - name: VDiskLoad
-        href: development/load-actors-vdisk.md
-      - name: PDiskWriteLoad
-        href: development/load-actors-pdisk-write.md
-      - name: PDiskReadLoad
-        href: development/load-actors-pdisk-read.md
-      - name: PDiskLogLoad
-        href: development/load-actors-pdisk-log.md
-      - name: MemoryLoad
-        href: development/load-actors-memory.md
-      - name: Stop
-        href: development/load-actors-stop.md
-
+- { name: Development,                                     include: { mode: link, path: development/toc_p.yaml } }
 # Footer
 - { name: Questions and answers,                        include: { mode: link, path: faq/toc_p.yaml } }
 - include: { mode: link, path: downloads/toc_p.yaml }
diff --git a/ydb/docs/ru/core/development/build-ya.md b/ydb/docs/ru/core/development/build-ya.md
new file mode 100644
index 00000000000..5bb1021ad94
--- /dev/null
+++ b/ydb/docs/ru/core/development/build-ya.md
@@ -0,0 +1,3 @@
+# Сборка и тестирование с использованием Ya Make
+
+В данный момент эта статья доступна только в англоязычном варианте.
\ No newline at end of file
diff --git a/ydb/docs/ru/core/development/index.md b/ydb/docs/ru/core/development/index.md
new file mode 100644
index 00000000000..07a1c7043bc
--- /dev/null
+++ b/ydb/docs/ru/core/development/index.md
@@ -0,0 +1,6 @@
+# Разработка YDB
+
+Данный раздел содержит материалы для разработчиков и контрибьюторов YDB.
+
+* [Сборка и тестирование с использованием Ya Make](build-ya.md)
+* [Работа над изменениями](suggest-change.md)
\ No newline at end of file
diff --git a/ydb/docs/ru/core/development/suggest-change.md b/ydb/docs/ru/core/development/suggest-change.md
new file mode 100644
index 00000000000..30fc1ea730e
--- /dev/null
+++ b/ydb/docs/ru/core/development/suggest-change.md
@@ -0,0 +1,3 @@
+# Процесс разработки: работа над изменениями кода YDB
+
+В данный момент эта статья доступна только в англоязычном варианте.
\ No newline at end of file
diff --git a/ydb/docs/ru/core/development/toc_i.yaml b/ydb/docs/ru/core/development/toc_i.yaml
new file mode 100644
index 00000000000..468e99251db
--- /dev/null
+++ b/ydb/docs/ru/core/development/toc_i.yaml
@@ -0,0 +1,29 @@
+items:
+- name: Сборка и тесты Ya
+  href: build-ya.md
+- name: Работа над изменениями
+  href: suggest-change.md
+- name: Ядро
+  items:
+  - name: Тестирование с помощью нагружающих акторов
+    items:
+    - name: Обзор
+      href: load-actors-overview.md
+    - name: KqpLoad
+      href: load-actors-kqp.md
+    - name: KeyValueLoad
+      href: load-actors-key-value.md
+    - name: StorageLoad
+      href: load-actors-storage.md
+    - name: VDiskLoad
+      href: load-actors-vdisk.md
+    - name: PDiskWriteLoad
+      href: load-actors-pdisk-write.md
+    - name: PDiskReadLoad
+      href: load-actors-pdisk-read.md
+    - name: PDiskLogLoad
+      href: load-actors-pdisk-log.md
+    - name: MemoryLoad
+      href: load-actors-memory.md
+    - name: Stop
+      href: load-actors-stop.md
diff --git a/ydb/docs/ru/core/development/toc_p.yaml b/ydb/docs/ru/core/development/toc_p.yaml
new file mode 100644
index 00000000000..3e62ad228bc
--- /dev/null
+++ b/ydb/docs/ru/core/development/toc_p.yaml
@@ -0,0 +1,4 @@
+items:
+- name: Обзор
+  href: index.md
+- include: { mode: link, path: toc_i.yaml }
\ No newline at end of file
diff --git a/ydb/docs/ru/core/toc_i.yaml b/ydb/docs/ru/core/toc_i.yaml
index 0223a33ba33..611c9b19668 100644
--- a/ydb/docs/ru/core/toc_i.yaml
+++ b/ydb/docs/ru/core/toc_i.yaml
@@ -18,33 +18,7 @@ items:
 - { name: Работа с YDB CLI,                        include: { mode: link, path: reference/ydb-cli/toc_p.yaml } }
 - { name: Работа с YDB SDK,                        include: { mode: link, path: reference/ydb-sdk/toc_p.yaml } }
 - { name: Работа с Kafka API,                      include: { mode: link, path: reference/kafka-api/toc_p.yaml } }
-- name: Разработка
-  # hidden: true
-  items:
-  - name: Ядро
-    items:
-    - name: Тестирование с помощью нагружающих акторов
-      items:
-      - name: Обзор
-        href: development/load-actors-overview.md
-      - name: KqpLoad
-        href: development/load-actors-kqp.md
-      - name: KeyValueLoad
-        href: development/load-actors-key-value.md
-      - name: StorageLoad
-        href: development/load-actors-storage.md
-      - name: VDiskLoad
-        href: development/load-actors-vdisk.md
-      - name: PDiskWriteLoad
-        href: development/load-actors-pdisk-write.md
-      - name: PDiskReadLoad
-        href: development/load-actors-pdisk-read.md
-      - name: PDiskLogLoad
-        href: development/load-actors-pdisk-log.md
-      - name: MemoryLoad
-        href: development/load-actors-memory.md
-      - name: Stop
-        href: development/load-actors-stop.md
+- { name: Разработка,                              include: { mode: link, path: development/toc_p.yaml } }
 
 # Footer
 - { name: Вопросы и ответы,                        include: { mode: link, path: faq/toc_p.yaml } }