@@ -5,122 +5,149 @@ All commands should be run from the project root directory.
55## Environment Management
66
77### ` make install-uv `
8+
89Installs the latest version of UV package manager.
910
1011** Usage:**
12+
1113``` bash
1214make install-uv
1315```
1416
1517### ` make install `
18+
1619Creates a fresh virtual environment and installs all dependencies (development, testing, linting, and documentation).
1720
1821** Usage:**
22+
1923``` bash
2024make install
2125```
2226
2327** What it does:**
28+
2429- Destroys any existing virtual environment
2530- Pins Python to version 3.12
2631- Creates ` .venv/ ` virtual environment
2732- Installs all dependencies with ` uv sync --all-extras --dev `
2833- Installs pre-commit hooks
2934
3035### ` make upgrade `
36+
3137Upgrades all dependencies to their latest stable versions and updates pre-commit hooks.
3238
3339** Usage:**
40+
3441``` bash
3542make upgrade
3643```
3744
3845** What it does:**
46+
3947- Updates ` uv.lock ` with latest dependency versions
4048- Updates pre-commit hook versions
4149
4250### ` make destroy `
51+
4352Removes the virtual environment completely.
4453
4554** Usage:**
55+
4656``` bash
4757make destroy
4858```
4959
5060## Building
5161
5262### ` make build-collector `
63+
5364Builds database collection script packages (ZIP files) for all supported databases.
5465
5566** Usage:**
67+
5668``` bash
5769make build-collector
5870```
5971
6072** Output:** Creates ZIP files in ` dist/ ` :
73+
6174- ` db-migration-assessment-collection-scripts-oracle.zip `
6275- ` db-migration-assessment-collection-scripts-sqlserver.zip `
6376- ` db-migration-assessment-collection-scripts-mysql.zip `
6477- ` db-migration-assessment-collection-scripts-postgres.zip `
6578
6679### ` make build `
80+
6781Builds both collection script packages and the Python wheel.
6882
6983** Usage:**
84+
7085``` bash
7186make build
7287```
7388
7489** What it does:**
90+
7591- Runs ` make build-collector `
7692- Runs ` uv build ` to create wheel and sdist
7793
7894** Output:** Creates in ` dist/ ` :
95+
7996- Collection script ZIP files
8097- ` dma-{version}-py3-none-any.whl `
8198- ` dma-{version}.tar.gz `
8299
83100### ` make clean `
101+
84102Removes all build artifacts, test files, and temporary files.
85103
86104** Usage:**
105+
87106``` bash
88107make clean
89108```
90109
91110** What it removes:**
111+
92112- ` dist/ ` , ` build/ ` , ` .eggs/ `
93113- ` *.egg-info ` , ` *.pyc ` , ` __pycache__/ `
94114- ` .pytest_cache ` , ` .ruff_cache ` , ` .mypy_cache `
95115- ` .coverage ` , ` coverage.xml ` , ` htmlcov/ `
96116
97117### ` make deep-clean `
118+
98119Performs a deep clean including virtual environment and UV cache.
99120
100121** Usage:**
122+
101123``` bash
102124make deep-clean
103125```
104126
105127## Testing
106128
107129### ` make test `
130+
108131Runs the full test suite with coverage reporting (Python 3.12).
109132
110133** Usage:**
134+
111135``` bash
112136make test
113137```
114138
115139** Equivalent to:**
140+
116141``` bash
117142uv run pytest -n 2 --cov
118143```
119144
120145### ` make test-all-pythons `
146+
121147Runs tests against all supported Python versions (3.9, 3.10, 3.11, 3.12, 3.13).
122148
123149** Usage:**
150+
124151``` bash
125152make test-all-pythons
126153```
@@ -146,14 +173,17 @@ uv run pytest --no-cov
146173## Linting and Code Quality
147174
148175### ` make lint `
176+
149177Runs all pre-commit hooks including ruff linting, formatting, and codespell.
150178
151179** Usage:**
180+
152181``` bash
153182make lint
154183```
155184
156185** What it runs:**
186+
157187- Python AST validation
158188- TOML/YAML/JSON validation
159189- Ruff linting and formatting
@@ -183,29 +213,35 @@ uv run codespell
183213## Documentation
184214
185215### ` make docs `
216+
186217Generates HTML documentation from Markdown files.
187218
188219** Usage:**
220+
189221``` bash
190222make docs
191223```
192224
193225** Output:** Creates documentation in ` site/ `
194226
195227### ` make serve-docs `
228+
196229Builds and serves documentation locally with auto-reload.
197230
198231** Usage:**
232+
199233``` bash
200234make serve-docs
201235```
202236
203237** Access:** Opens at ` http://localhost:8000 `
204238
205239### ` make doc-privs `
240+
206241Extracts Oracle privilege requirements from code and updates documentation.
207242
208243** Usage:**
244+
209245``` bash
210246make doc-privs
211247```
@@ -214,28 +250,32 @@ make doc-privs
214250
215251## Version Management
216252
217- ### ` make pre-release `
253+ ### ` make release `
254+
218255Bumps the version number, updates all version references, and builds release artifacts.
219256
220257** Usage:**
258+
221259``` bash
222260# Bump patch version (e.g., 4.3.44 → 4.3.45)
223- make pre- release increment =patch
261+ make release bump =patch
224262
225263# Bump minor version (e.g., 4.3.44 → 4.4.0)
226- make pre- release increment =minor
264+ make release bump =minor
227265
228266# Bump major version (e.g., 4.3.44 → 5.0.0)
229- make pre- release increment =major
267+ make release bump =major
230268```
231269
232270** What it does:**
271+
2332721 . Generates documentation
2342732 . Cleans build artifacts
2352743 . Bumps version in all files using ` bump-my-version `
2362754 . Builds collection scripts and wheel
237276
238277** Files updated:**
278+
239279- ` pyproject.toml `
240280- ` uv.lock `
241281- ` scripts/masker/dma-collection-masker `
@@ -357,5 +397,5 @@ uv sync --locked
357397| Build everything | ` make build ` |
358398| Clean artifacts | ` make clean ` |
359399| Serve docs | ` make serve-docs ` |
360- | Bump version | ` make pre- release increment =patch ` |
400+ | Bump version | ` make release bump =patch ` |
361401| Run CLI | ` uv run dma --help ` |
0 commit comments