Public Access
emil
19eb57445d
Post-merge / detect-type (push) Successful in 11s
Post-merge / validate-commit-msg (push) Successful in 9s
Post-merge / release (push) Successful in 17s
Post-merge / publish (push) Has been skipped
Post-merge / vikunja (push) Successful in 19s
Post-merge / configure-repo (push) Successful in 15s
Post-merge / sync-wiki (push) Successful in 47s
Post-merge / badges (push) Successful in 42s
162 lines
4.3 KiB
Markdown
162 lines
4.3 KiB
Markdown
# Getting Started with devx
|
|
|
|
This guide walks you through installing devx, configuring it for your project,
|
|
and setting up a complete CI/CD pipeline.
|
|
|
|
## Prerequisites
|
|
|
|
- **Python 3.12+**
|
|
- **A Gitea instance** with Actions enabled
|
|
- **A Gitea API token** with repo, workflow, and organization scopes
|
|
- **(Optional) Vikunja API token** for task tracking integration
|
|
|
|
## Installation
|
|
|
|
devx is published to the Gitea PyPI registry. Configure pip to use it:
|
|
|
|
```bash
|
|
# Configure Gitea PyPI registry
|
|
pip config set global.extra-index-url https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
|
|
|
|
# Install devx
|
|
pip install devx
|
|
```
|
|
|
|
Or install from source:
|
|
|
|
```bash
|
|
git clone https://git.oblachno.oblachno.fyi/oblachno-oss/devx.git
|
|
cd devx
|
|
make setup
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### 1. Configure environment variables
|
|
|
|
Create a `.env` file in your project root:
|
|
|
|
```bash
|
|
CI_GITEA_TOKEN=your_gitea_api_token
|
|
VIKUNJA_TOKEN=your_vikunja_api_token # optional
|
|
```
|
|
|
|
### 2. Add devx to your project
|
|
|
|
Add devx to your `pyproject.toml`:
|
|
|
|
```toml
|
|
[project]
|
|
dependencies = [
|
|
"devx>=0.27.0",
|
|
]
|
|
|
|
[project.optional-dependencies]
|
|
dev = [
|
|
"devx[dev]>=0.27.0",
|
|
]
|
|
```
|
|
|
|
### 3. Set up the Makefile
|
|
|
|
devx provides a shared Makefile fragment. Add this to your `Makefile`:
|
|
|
|
```makefile
|
|
include devx.mak
|
|
```
|
|
|
|
Run `devx tools setup` to install all development tools (actionlint, git-cliff,
|
|
tea CLI, etc.) and configure pre-commit hooks.
|
|
|
|
### 4. Create the docs structure
|
|
|
|
devx expects a `docs/` directory with at minimum:
|
|
|
|
```
|
|
docs/
|
|
├── index.md # Documentation home page
|
|
├── mapping.json # Wiki page title mappings
|
|
├── user/ # User-facing documentation
|
|
│ └── cli-commands.md
|
|
└── tech/ # Technical documentation
|
|
├── architecture.md
|
|
└── ci-cd-workflow.md
|
|
```
|
|
|
|
Example `docs/mapping.json`:
|
|
|
|
```json
|
|
{
|
|
"index.md": "Home",
|
|
"user/cli-commands.md": "CLI-Commands",
|
|
"tech/architecture.md": "Architecture",
|
|
"tech/ci-cd-workflow.md": "CI-CD-Workflow"
|
|
}
|
|
```
|
|
|
|
### 5. Set up CI workflows
|
|
|
|
Create `.gitea/workflows/ci.yml` and `.gitea/workflows/post-merge.yml` in your
|
|
project. See the [CI/CD Workflow guide](../tech/ci-cd-workflow.md) for details.
|
|
|
|
### 6. Configure release settings
|
|
|
|
Add a `cliff.toml` for git-cliff-based versioning:
|
|
|
|
```bash
|
|
devx tools generate-cliff-config
|
|
```
|
|
|
|
Add `[tool.devx]` section to `pyproject.toml` for project-specific config:
|
|
|
|
```toml
|
|
[tool.devx]
|
|
# Vikunja project ID for task tracking
|
|
vikunja_project_id = 6
|
|
|
|
[tool.devx.classify]
|
|
# File patterns that are infrastructure (no release needed)
|
|
infrastructure = [
|
|
".gitea/**",
|
|
"docs/**",
|
|
"tests/**",
|
|
"AGENTS.md",
|
|
"README.md",
|
|
"CHANGELOG.md",
|
|
]
|
|
```
|
|
|
|
## Available Tools
|
|
|
|
### CI/CD Automation (`devx.ci.*`)
|
|
|
|
- `devx.ci.release` — Automated semver versioning and tagging
|
|
- `devx.ci.publish` — Package publishing to Gitea PyPI registry
|
|
- `devx.ci.auto_merge` — Squash-merge automation with task ID validation
|
|
- `devx.ci.pr_review` — Automated PR review with inline comments
|
|
- `devx.ci.classify_changes` — User-facing vs workflow-only change detection
|
|
- `devx.ci.sync_wiki` — Push docs/ to Gitea wiki
|
|
- `devx.ci.doc_coverage` — Documentation coverage checker
|
|
- `devx.ci.lint_docs` — Documentation linter (structure, links, headings)
|
|
- `devx.ci.check_translations` — i18n translation completeness checker
|
|
- `devx.ci.notify_failure` — Create Gitea issues on CI failures
|
|
- `devx.ci.distribute_files` — Parallel test file distribution
|
|
- `devx.ci.distribute_items` — Parallel item distribution across runners
|
|
- `devx.ci.discover_runners` — Dynamic runner discovery via Gitea API
|
|
|
|
### Development Tools (`devx.tools.*`)
|
|
|
|
- `devx.tools.setup` — Environment setup (venv, deps, hooks, tools)
|
|
- `devx.tools.install_tools` — Install CI/CD tools (actionlint, git-cliff, tea)
|
|
- `devx.tools.create_task` — Create Vikunja tasks
|
|
- `devx.tools.create_pr` — Create Gitea PRs with task ID in title
|
|
- `devx.tools.configure_repo` — Configure branch protection and labels
|
|
- `devx.tools.generate_badges` — Generate quality badge SVGs
|
|
- `devx.tools.check_test_speed` — Enforce test execution speed limits
|
|
|
|
## Next Steps
|
|
|
|
- Read the [CLI Commands reference](cli-commands.md) for all available commands
|
|
- Read the [Architecture guide](../tech/architecture.md) to understand internals
|
|
- Read the [CI/CD Workflow guide](../tech/ci-cd-workflow.md) for pipeline details
|