Skip to content

Commit b38b3c0

Browse files
behitekbehitek
committed
add git and python convenstion docs
1 parent 882e27e commit b38b3c0

5 files changed

Lines changed: 350 additions & 3 deletions

File tree

‎blog/2025-05-22-modern-python-project-setup.md‎

Whitespace-only changes.

‎docs/git.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: Git Working Rules
3+
tags: [git]
4+
description: My personal Git cheat sheet
5+
image: https://upload.wikimedia.org/wikipedia/commons/thumb/e/e0/Git-logo.svg/1024px-Git-logo.svg.png
6+
---
7+
8+
### 👥 Roles
9+
10+
* **Repository Owner**
11+
12+
* Manage repo access
13+
* Prevent direct commits to `develop`, `test`, `uat`, `prod`
14+
* Review merge important branches: `test`, `uat`, `prod`
15+
16+
* **Maintainers (Lead Devs)**
17+
18+
* Manage `release` & `hotfix` branches
19+
* Review & merge pull requests (PRs)
20+
* Help define working process
21+
22+
* **Developers**
23+
24+
* Create `feature/*`, `bugfix/*`, or `hotfix/*` branches from `develop`
25+
* Submit PRs to `develop` when done.
26+
* Include detailed description in PRs.
27+
* Review and improve PRs.
28+
29+
* **DevOps**
30+
31+
* Manage deployments and system config
32+
* Deploy code from `develop`, `test`, `uat`, `prod`
33+
34+
---
35+
36+
### 🔁 Git Flow
37+
38+
> Dev is the default branch. All development starts from here.
39+
40+
1. **`develop`** – Active development (default branch)
41+
42+
* All new work branches are created from here
43+
* Only `develop` can merge into `test`
44+
45+
2. **`test`** – Internal QA/testing
46+
47+
* Only receives merges from `develop`
48+
* Can merge into `uat`
49+
50+
3. **`uat`** – Pre-release, client/user testing
51+
52+
* Only receives merges from `test`
53+
* Can merge into `prod`
54+
55+
4. **`prod`** – Final, stable version
56+
57+
* Only receives merges from `uat`
58+
59+
---
60+
61+
### 🪴 Branching Rules
62+
63+
* You **must use one of the following prefixes** for branches:
64+
65+
* `feature/*` – For new features or enhancements
66+
* `bugfix/*` – For fixing bugs found during development
67+
* `hotfix/*` – For urgent, production-critical fixes
68+
* All branches must be created from `develop`
69+
* Example: `feature/user-login`, `bugfix/payment-crash`, `hotfix/api-down`
70+
71+
---
72+
73+
### ✍️ Committing
74+
75+
* Write **clear, meaningful** commit messages
76+
* Avoid **unrelated changes** in a single commit
77+
78+
---
79+
80+
### 🔀 Merging
81+
82+
* All changes go through **Merge Requests (MRs)**
83+
* MRs must be **code reviewed**
84+
* **Use rebase on feature branches** to keep history clean
85+
* **Use merge into `develop` and above** to retain full collaboration history
86+
* Merge paths must follow environment flow:
87+
88+
* `develop` → `test` → `uat` → `prod`
89+
* Auto-merge only if tests pass (future feature)
90+
* Delete merged branches (except protected ones)
91+
92+
---
93+
94+
### 🏷️ Versioning & Clean Code
95+
96+
* Use **tags** for releases
97+
* Use `.gitignore` for non-tracked files (e.g. `.env`)
98+
* Never commit **sensitive info** (keys, tokens)
99+
* Document environment variables in `README`
100+
* No **absolute paths** in code (e.g. `/home/user/...`)
101+
102+
---
103+
104+
### 💡 Best Practices
105+
106+
* **CI/CD**: Auto-test & build on commit
107+
* **Conflict resolution**: Resolve before merge
108+
* **Repo size**: Keep small (limit: 5–20MB)
109+
* **Code conventions**: Follow team style guides
110+
* **Code reviews**: Review before merging
111+
* **Documentation**: Keep everything documented
112+
* **Backup**: Regularly back up repo
113+
* **Hooks**: Use Git hooks to validate code before commit
114+
* **Cleanup**: Remove unused branches regularly
115+
116+
---
117+
118+
### 📘 References
119+
120+
* [Atlassian Git Flow Guide](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)
121+
* [Git Cheat Sheet (GitHub)](https://education.github.com/git-cheat-sheet-education.pdf)
122+
* [Learn Git Branching (interactive)](https://learngitbranching.js.org/)
123+
* [Pro Git Book](https://git-scm.com/book/en/v2)

‎docs/python-convention.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
---
2+
title: Python Code Convention
3+
tags: [python, coding-convention]
4+
description: My personal Python code convention
5+
image: /img/docs/python.jpeg
6+
---
7+
8+
## 1. Target Audience
9+
10+
Developers building Python services, tools, or pipelines.
11+
12+
---
13+
14+
## 2. Coding Style
15+
16+
Follow [PEP 8](https://peps.python.org/pep-0008/) style. Key rules:
17+
18+
### Indentation and Line Length
19+
20+
* 4 spaces (no tabs)
21+
* Max 79 characters per line
22+
23+
### Imports
24+
25+
* Group in order: standard lib → third-party → internal
26+
* One import per line
27+
28+
### Whitespace
29+
30+
* Space around operators and after commas
31+
* No space inside brackets
32+
33+
### Naming Conventions
34+
35+
* Variables/functions: `snake_case`
36+
* Classes: `PascalCase`
37+
* Constants: `ALL_CAPS`
38+
* Protected/private: `_name`, `__name`
39+
40+
### Comments & Docstrings
41+
42+
* Use docstrings for all public code
43+
* Use complete sentences
44+
* Add `# TODO:` or `# NOTE:` where needed
45+
46+
---
47+
48+
## 3. Project Structure & Environment
49+
50+
Use modern Python project tools for clarity and maintainability:
51+
52+
| Tool | Use Case |
53+
| -------- | ------------------------------- |
54+
| `poetry` | Dependency & virtualenv manager |
55+
| `uv` | Fast `pip` & `venv` alternative |
56+
| `conda` | (Optional) Data/ML workflows |
57+
58+
### Recommended Layout
59+
60+
```bash
61+
your_project/
62+
├── pyproject.toml
63+
├── src/
64+
│ └── your_module/
65+
└── tests/
66+
```
67+
68+
> Using `src/` layout helps prevent import issues and improves test isolation.
69+
70+
---
71+
72+
## 4. Path Handling
73+
74+
Always avoid `abspath`. Use `pathlib` with relative paths.
75+
76+
### ❌ Not recommended:
77+
78+
```python
79+
import os
80+
path = os.path.abspath(os.path.join(os.path.dirname(__file__), "file.txt"))
81+
```
82+
83+
### ✅ Recommended:
84+
85+
```python
86+
from pathlib import Path
87+
88+
path = Path(__file__).parent / "file.txt"
89+
```
90+
91+
---
92+
93+
## 5. Linting & Formatting
94+
95+
Use [`ruff`](https://docs.astral.sh/ruff/) with [`pre-commit`](https://pre-commit.com/).
96+
97+
### Setup Steps
98+
99+
1. Install:
100+
101+
```bash
102+
pip install pre-commit
103+
```
104+
105+
2. Create `.pre-commit-config.yaml`:
106+
107+
```yaml
108+
repos:
109+
- repo: https://github.com/pre-commit/pre-commit-hooks
110+
rev: v5.0.0
111+
hooks:
112+
- id: trailing-whitespace
113+
- id: check-yaml
114+
- repo: https://github.com/astral-sh/ruff-pre-commit
115+
rev: v0.11.8
116+
hooks:
117+
- id: ruff
118+
```
119+
120+
3. Install hooks:
121+
122+
```bash
123+
pre-commit install
124+
```
125+
126+
### Ruff Config (`pyproject.toml`)
127+
128+
```toml
129+
[tool.ruff]
130+
select = ["E", "F"]
131+
ignore = ["E501"] # Ignore line length for now
132+
```
133+
134+
### Usage
135+
136+
```bash
137+
ruff check src/
138+
ruff check src/ --fix
139+
```
140+
141+
---
142+
143+
## 6. Editor Integration
144+
145+
### Visual Studio Code
146+
147+
* Enable **Format on Save**
148+
* Install the **Ruff** extension
149+
150+
---
151+
152+
## 7. Python Version
153+
154+
All code should support **Python 3.11+**. Set it explicitly in `pyproject.toml`:
155+
156+
```toml
157+
[tool.poetry.dependencies]
158+
python = ">=3.11"
159+
```
160+
161+
---
162+
163+
## 8. Testing Conventions
164+
165+
* Use `pytest`
166+
* Place tests in the `tests/` directory
167+
* Name tests `test_*.py`
168+
* Test function names should describe expected behavior
169+
170+
Example:
171+
172+
```python
173+
def test_parse_valid_config():
174+
...
175+
```
176+
177+
---
178+
179+
## 9. Logging and Config Management
180+
181+
Use the team's **standardized logging and config templates**:
182+
183+
* Import from our shared utility module
184+
* Follow the documented interfaces in the shared repo
185+
186+
> 🧩 *\[PLACEHOLDER: Insert internal repo link or code snippet here]*
187+
> Example usage:
188+
>
189+
> ```python
190+
> from our_utils.logging import get_logger
191+
> from our_utils.config import load_config
192+
> ```
193+
194+
---
195+
196+
## 10. Git Ignore Rules
197+
198+
Common `.gitignore` entries:
199+
200+
```gitignore
201+
.venv/
202+
__pycache__/
203+
*.py[cod]
204+
.ruff_cache/
205+
.mypy_cache/
206+
```
207+
208+
---
209+
210+
## 11. References
211+
212+
* [PEP 8 – Style Guide for Python Code](https://peps.python.org/pep-0008/)
213+
* [Ruff Docs](https://docs.astral.sh/ruff/)
214+
* [Pre-commit Docs](https://pre-commit.com/)
215+
* [Hypermodern Python Guide](https://cjolowicz.github.io/posts/hypermodern-python-01-setup/)
216+
* [Pytest Docs](https://docs.pytest.org/en/stable/)

‎docusaurus.config.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ const internetProfiles = {
2525
to: "blog",
2626
},
2727
docs: {
28-
label: "Tutorials",
28+
label: "Docs",
2929
to: "docs",
3030
},
3131
projects: {
@@ -70,7 +70,7 @@ module.exports = {
7070
{
7171
to: "docs/",
7272
activeBasePath: "docs",
73-
label: "Tutorials",
73+
label: "Docs",
7474
position: "right",
7575
},
7676
{ to: "blog/", label: "Blog", position: "right" },

‎sidebars.js‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,14 @@ module.exports = {
2323
"algorithms/bfs",
2424
"algorithms/dfs",
2525
]
26-
}
26+
},
27+
{
28+
type: "doc",
29+
id: "git",
30+
},
31+
{
32+
type: "doc",
33+
id: "python-convention",
34+
},
2735
]
2836
};

0 commit comments

Comments
 (0)