Skip to content

Commit 440b079

Browse files
polRkpolRk
committed
docs: update CONTRIBUTING.md to reference BUILD.md for development environment setup
Signed-off-by: Vladislav Polyakov <polRk@ydb.tech>
1 parent 16e1876 commit 440b079

File tree

2 files changed

+114
-108
lines changed

2 files changed

+114
-108
lines changed

‎BUILD.md

Lines changed: 113 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,118 @@
22

33
This document has detailed instructions on how to build ydb-python-sdk from source and run style and unit tests.
44

5+
## Development Environment Setup
6+
7+
### Using Dev Containers (Recommended)
8+
9+
This repository includes a complete development environment using Docker containers that provides everything you need to start contributing immediately. The devcontainer setup includes:
10+
11+
- **Python 3.9** development environment with all necessary dependencies
12+
- **YDB server** running locally in a container
13+
- **Pre-configured tools**: Git, GitHub CLI, YDB CLI, and essential Python packages
14+
- **VS Code extensions**: Python development tools, linting, formatting, and debugging support
15+
16+
#### Prerequisites
17+
18+
- [Docker](https://www.docker.com/get-started) installed and running
19+
- [VS Code](https://code.visualstudio.com/) with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
20+
21+
#### Quick Start with Dev Containers
22+
23+
1. Clone the repository:
24+
```bash
25+
git clone https://github.com/ydb-platform/ydb-python-sdk.git
26+
cd ydb-python-sdk
27+
```
28+
29+
2. Open in VS Code:
30+
```bash
31+
code .
32+
```
33+
34+
3. When prompted, click "Reopen in Container" or use the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and select "Dev Containers: Reopen in Container"
35+
36+
4. Wait for the container to build and start (first time may take a few minutes)
37+
38+
5. The development environment is ready! You can now run tests, debug code, and develop new features.
39+
40+
### Using GitHub Codespaces
41+
42+
GitHub Codespaces provides a cloud-based development environment that works directly in your browser or VS Code. It's perfect for quick contributions without setting up a local environment.
43+
44+
#### Quick Start with Codespaces
45+
46+
1. Navigate to the [repository on GitHub](https://github.com/ydb-platform/ydb-python-sdk)
47+
2. Click the green "Code" button
48+
3. Select the "Codespaces" tab
49+
4. Click "Create codespace on main" (or your desired branch)
50+
5. Wait for the environment to initialize (usually 2-3 minutes)
51+
6. Start coding directly in the browser or connect with your local VS Code
52+
53+
#### What's Included in the Development Environment
54+
55+
When you use either dev containers or Codespaces, the following environment is automatically set up:
56+
57+
**Container Services:**
58+
- **SDK Container (`sdk`)**: Your main development environment running Python 3.9 on Debian Bookworm
59+
- **YDB Container (`ydb`)**: Local YDB server (version 25.1) for testing and development
60+
61+
**Development Tools:**
62+
- **YDB CLI**: Pre-installed and configured to connect to the local YDB instance
63+
- **Python Environment**: All project dependencies installed via `pip install -e .`
64+
- **Git Configuration**: Automatic setup for signed commits (if configured)
65+
- **VS Code Extensions**: Python development stack including linting, formatting, and debugging
66+
67+
**Network Configuration:**
68+
- **Port 2135**: YDB gRPC with TLS
69+
- **Port 2136**: YDB gRPC without TLS
70+
- **Port 8765**: YDB Monitoring interface
71+
- These ports are automatically forwarded and accessible from your local machine
72+
73+
**Environment Variables:**
74+
The following environment variables are pre-configured for immediate use:
75+
- `YDB_CONNECTION_STRING=grpc://ydb:2136/local` - Standard connection
76+
- `YDB_CONNECTION_STRING_SECURE=grpcs://ydb:2135/local` - Secure connection
77+
- `YDB_SSL_ROOT_CERTIFICATES_FILE=/ydb_certs/ca.pem` - SSL certificates
78+
- `YDB_STATIC_CREDENTIALS_USER=root` and `YDB_STATIC_CREDENTIALS_PASSWORD=1234` - Test credentials
79+
80+
**Automatic Setup Process:**
81+
1. **Initialize**: Git configuration for signed commits and user settings
82+
2. **Post-Create**: YDB CLI profile setup and GPG configuration for SSH signing
83+
3. **Post-Start**: Installation of Python dependencies, SDK package, and testing tools (tox)
84+
85+
#### Running Tests in the Development Environment
86+
87+
Once your environment is ready, you can run the test suite:
88+
89+
```bash
90+
# Run all tests
91+
tox
92+
93+
# Run specific test categories
94+
python -m pytest tests/
95+
96+
# Run with specific Python version
97+
tox -e py39
98+
```
99+
100+
#### Connecting to the Local YDB Instance
101+
102+
The YDB CLI is pre-configured to connect to the local instance:
103+
104+
```bash
105+
# Run a simple query
106+
echo "SELECT 1;" | ydb
107+
108+
# Access the web interface
109+
# Open http://localhost:8765 in your browser (when using local dev containers)
110+
# In codespaces you can access it via the provided URL in the terminal output.
111+
```
112+
113+
## Manual Setup (Alternative)
114+
115+
If you prefer to set up your development environment manually without using dev containers:
116+
5117
### Pre-requisites
6118

7119
- Install [Docker](https://docs.docker.com/engine/install/).
@@ -52,4 +164,4 @@ Use the command below for regenerate protobuf code.
52164

53165
```sh
54166
make protobuf
55-
```
167+
```

‎CONTRIBUTING.md

Lines changed: 1 addition & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -4,113 +4,7 @@
44

55
YDB is a free and open project and we appreciate to receive contributions from our community.
66

7-
## Development Environment Setup
8-
9-
### Using Dev Containers (Recommended)
10-
11-
This repository includes a complete development environment using Docker containers that provides everything you need to start contributing immediately. The devcontainer setup includes:
12-
13-
- **Python 3.9** development environment with all necessary dependencies
14-
- **YDB server** running locally in a container
15-
- **Pre-configured tools**: Git, GitHub CLI, YDB CLI, and essential Python packages
16-
- **VS Code extensions**: Python development tools, linting, formatting, and debugging support
17-
18-
#### Prerequisites
19-
20-
- [Docker](https://www.docker.com/get-started) installed and running
21-
- [VS Code](https://code.visualstudio.com/) with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
22-
23-
#### Quick Start with Dev Containers
24-
25-
1. Clone the repository:
26-
```bash
27-
git clone https://github.com/ydb-platform/ydb-python-sdk.git
28-
cd ydb-python-sdk
29-
```
30-
31-
2. Open in VS Code:
32-
```bash
33-
code .
34-
```
35-
36-
3. When prompted, click "Reopen in Container" or use the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and select "Dev Containers: Reopen in Container"
37-
38-
4. Wait for the container to build and start (first time may take a few minutes)
39-
40-
5. The development environment is ready! You can now run tests, debug code, and develop new features.
41-
42-
### Using GitHub Codespaces
43-
44-
GitHub Codespaces provides a cloud-based development environment that works directly in your browser or VS Code. It's perfect for quick contributions without setting up a local environment.
45-
46-
#### Quick Start with Codespaces
47-
48-
1. Navigate to the [repository on GitHub](https://github.com/ydb-platform/ydb-python-sdk)
49-
2. Click the green "Code" button
50-
3. Select the "Codespaces" tab
51-
4. Click "Create codespace on main" (or your desired branch)
52-
5. Wait for the environment to initialize (usually 2-3 minutes)
53-
6. Start coding directly in the browser or connect with your local VS Code
54-
55-
#### What's Included in the Development Environment
56-
57-
When you use either dev containers or Codespaces, the following environment is automatically set up:
58-
59-
**Container Services:**
60-
- **SDK Container (`sdk`)**: Your main development environment running Python 3.9 on Debian Bookworm
61-
- **YDB Container (`ydb`)**: Local YDB server (version 25.1) for testing and development
62-
63-
**Development Tools:**
64-
- **YDB CLI**: Pre-installed and configured to connect to the local YDB instance
65-
- **Python Environment**: All project dependencies installed via `pip install -e .`
66-
- **Git Configuration**: Automatic setup for signed commits (if configured)
67-
- **VS Code Extensions**: Python development stack including linting, formatting, and debugging
68-
69-
**Network Configuration:**
70-
- **Port 2135**: YDB gRPC with TLS
71-
- **Port 2136**: YDB gRPC without TLS
72-
- **Port 8765**: YDB Monitoring interface
73-
- These ports are automatically forwarded and accessible from your local machine
74-
75-
**Environment Variables:**
76-
The following environment variables are pre-configured for immediate use:
77-
- `YDB_CONNECTION_STRING=grpc://ydb:2136/local` - Standard connection
78-
- `YDB_CONNECTION_STRING_SECURE=grpcs://ydb:2135/local` - Secure connection
79-
- `YDB_SSL_ROOT_CERTIFICATES_FILE=/ydb_certs/ca.pem` - SSL certificates
80-
- `YDB_STATIC_CREDENTIALS_USER=root` and `YDB_STATIC_CREDENTIALS_PASSWORD=1234` - Test credentials
81-
82-
**Automatic Setup Process:**
83-
1. **Initialize**: Git configuration for signed commits and user settings
84-
2. **Post-Create**: YDB CLI profile setup and GPG configuration for SSH signing
85-
3. **Post-Start**: Installation of Python dependencies, SDK package, and testing tools (tox)
86-
87-
#### Running Tests in the Development Environment
88-
89-
Once your environment is ready, you can run the test suite:
90-
91-
```bash
92-
# Run all tests
93-
tox
94-
95-
# Run specific test categories
96-
python -m pytest tests/
97-
98-
# Run with specific Python version
99-
tox -e py39
100-
```
101-
102-
#### Connecting to the Local YDB Instance
103-
104-
The YDB CLI is pre-configured to connect to the local instance:
105-
106-
```bash
107-
# Run a simple query
108-
echo "SELECT 1;" | ydb
109-
110-
# Access the web interface
111-
# Open http://localhost:8765 in your browser (when using local dev containers)
112-
# In codespaces you can access it via the provided URL in the terminal output.
113-
```
7+
For information about setting up your development environment, please see [BUILD.md](BUILD.md).
1148

1159
## Contributing code changes
11610

0 commit comments

Comments
 (0)