Skip to content

Commit d1cef81

Browse files
polRkpolRk
committed
docs: update CONTRIBUTING.md to reference BUILD.md for development environment setup
Signed-off-by: Vladislav Polyakov <[email protected]>
1 parent 16e1876 commit d1cef81

File tree

2 files changed

+109
-109
lines changed

2 files changed

+109
-109
lines changed

‎BUILD.md

Lines changed: 108 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

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

5-
### Pre-requisites
5+
## Pre-requisites
66

77
- Install [Docker](https://docs.docker.com/engine/install/).
88
- Install [Python](https://docs.python.org/3.8/)
@@ -52,4 +52,110 @@ Use the command below for regenerate protobuf code.
5252

5353
```sh
5454
make protobuf
55-
```
55+
```
56+
57+
## Using Dev Containers
58+
59+
This repository includes a complete development environment using Docker containers that provides everything you need to start contributing immediately. The devcontainer setup includes:
60+
61+
- **Python 3.9** development environment with all necessary dependencies
62+
- **YDB server** running locally in a container
63+
- **Pre-configured tools**: Git, GitHub CLI, YDB CLI, and essential Python packages
64+
- **VS Code extensions**: Python development tools, linting, formatting, and debugging support
65+
66+
### Prerequisites
67+
68+
- [Docker](https://www.docker.com/get-started) installed and running
69+
- [VS Code](https://code.visualstudio.com/) with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
70+
71+
### Quick Start with Dev Containers
72+
73+
1. Clone the repository:
74+
```bash
75+
git clone https://github.com/ydb-platform/ydb-python-sdk.git
76+
cd ydb-python-sdk
77+
```
78+
79+
2. Open in VS Code:
80+
```bash
81+
code .
82+
```
83+
84+
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"
85+
86+
4. Wait for the container to build and start (first time may take a few minutes)
87+
88+
5. The development environment is ready! You can now run tests, debug code, and develop new features.
89+
90+
### Using GitHub Codespaces
91+
92+
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.
93+
94+
#### Quick Start with Codespaces
95+
96+
1. Navigate to the [repository on GitHub](https://github.com/ydb-platform/ydb-python-sdk)
97+
2. Click the green "Code" button
98+
3. Select the "Codespaces" tab
99+
4. Click "Create codespace on main" (or your desired branch)
100+
5. Wait for the environment to initialize (usually 2-3 minutes)
101+
6. Start coding directly in the browser or connect with your local VS Code
102+
103+
### What's Included in the Development Environment
104+
105+
When you use either dev containers or Codespaces, the following environment is automatically set up:
106+
107+
**Container Services:**
108+
- **SDK Container (`sdk`)**: Your main development environment running Python 3.9 on Debian Bookworm
109+
- **YDB Container (`ydb`)**: Local YDB server (version 25.1) for testing and development
110+
111+
**Development Tools:**
112+
- **YDB CLI**: Pre-installed and configured to connect to the local YDB instance
113+
- **Python Environment**: All project dependencies installed via `pip install -e .`
114+
- **Git Configuration**: Automatic setup for signed commits (if configured)
115+
- **VS Code Extensions**: Python development stack including linting, formatting, and debugging
116+
117+
**Network Configuration:**
118+
- **Port 2135**: YDB gRPC with TLS
119+
- **Port 2136**: YDB gRPC without TLS
120+
- **Port 8765**: YDB Monitoring interface
121+
- These ports are automatically forwarded and accessible from your local machine
122+
123+
**Environment Variables:**
124+
The following environment variables are pre-configured for immediate use:
125+
- `YDB_CONNECTION_STRING=grpc://ydb:2136/local` - Standard connection
126+
- `YDB_CONNECTION_STRING_SECURE=grpcs://ydb:2135/local` - Secure connection
127+
- `YDB_SSL_ROOT_CERTIFICATES_FILE=/ydb_certs/ca.pem` - SSL certificates
128+
- `YDB_STATIC_CREDENTIALS_USER=root` and `YDB_STATIC_CREDENTIALS_PASSWORD=1234` - Test credentials
129+
130+
**Automatic Setup Process:**
131+
1. **Initialize**: Git configuration for signed commits and user settings
132+
2. **Post-Create**: YDB CLI profile setup and GPG configuration for SSH signing
133+
3. **Post-Start**: Installation of Python dependencies, SDK package, and testing tools (tox)
134+
135+
### Running Tests in the Development Environment
136+
137+
Once your environment is ready, you can run the test suite:
138+
139+
```bash
140+
# Run all tests
141+
tox
142+
143+
# Run specific test categories
144+
python -m pytest tests/
145+
146+
# Run with specific Python version
147+
tox -e py39
148+
```
149+
150+
### Connecting to the Local YDB Instance
151+
152+
The YDB CLI is pre-configured to connect to the local instance:
153+
154+
```bash
155+
# Run a simple query
156+
echo "SELECT 1;" | ydb
157+
158+
# Access the web interface
159+
# Open http://localhost:8765 in your browser (when using local dev containers)
160+
# In codespaces you can access it via the provided URL in the terminal output.
161+
```

‎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)