Skip to content

Commit 0ada0c2

Browse files
TomKaltofenTomKaltofen
committed
feat: initial setup
1 parent 0f628ef commit 0ada0c2

27 files changed

Lines changed: 583 additions & 1 deletion

‎.github/workflows/release.yaml‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: write
11+
issues: write
12+
pull-requests: write
13+
14+
jobs:
15+
github_release:
16+
name: GitHub Release
17+
runs-on: ubuntu-latest
18+
outputs:
19+
new_release_published: ${{ steps.semantic.outputs.new_release_published }}
20+
new_release_version: ${{ steps.semantic.outputs.new_release_version }}
21+
steps:
22+
- name: Checkout
23+
uses: actions/checkout@v4
24+
with:
25+
fetch-depth: 0
26+
token: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
27+
28+
- name: Setup Node.js
29+
uses: actions/setup-node@v4
30+
with:
31+
node-version: "lts/*"
32+
33+
- name: Install semantic-release plugins
34+
run: |
35+
npm install -g semantic-release \
36+
@semantic-release/commit-analyzer \
37+
@semantic-release/release-notes-generator \
38+
@semantic-release/exec \
39+
@semantic-release/github \
40+
@semantic-release/git \
41+
conventional-changelog-conventionalcommits
42+
43+
- name: Semantic Release (dry-run)
44+
env:
45+
GITHUB_TOKEN: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
46+
run: npx semantic-release --dry-run
47+
48+
- name: Semantic Release
49+
id: semantic
50+
env:
51+
GITHUB_TOKEN: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
52+
run: npx semantic-release
53+
54+
publish:
55+
name: Publish to PyPI
56+
runs-on: ubuntu-latest
57+
needs: github_release
58+
if: needs.github_release.outputs.new_release_published == 'true'
59+
steps:
60+
- name: Checkout
61+
uses: actions/checkout@v4
62+
with:
63+
ref: main
64+
fetch-depth: 0
65+
66+
- name: Pull latest changes
67+
run: git pull origin main
68+
69+
- name: Setup Python
70+
uses: actions/setup-python@v5
71+
with:
72+
python-version: "3.10"
73+
74+
- name: Install build tools
75+
run: pip install build twine
76+
77+
- name: Build package
78+
run: python -m build
79+
80+
- name: Publish to PyPI
81+
env:
82+
TWINE_USERNAME: __token__
83+
TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
84+
run: twine upload dist/*

‎.github/workflows/test.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: Tests
2+
3+
on:
4+
push:
5+
branches: ["*"]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
python-version: ["3.10", "3.11", "3.12", "3.13"]
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Set up Python ${{ matrix.python-version }}
20+
uses: actions/setup-python@v5
21+
with:
22+
python-version: ${{ matrix.python-version }}
23+
24+
- name: Install tox
25+
run: |
26+
python -m pip install --upgrade pip
27+
python -m pip install uv
28+
uv tool install tox --with tox-uv
29+
30+
- name: Run tox
31+
run: tox

‎.releaserc.yaml‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
branches:
2+
- main
3+
4+
tagFormat: ${version}
5+
6+
plugins:
7+
- - "@semantic-release/commit-analyzer"
8+
- preset: conventionalcommits
9+
releaseRules:
10+
- type: feat
11+
release: minor
12+
- type: fix
13+
release: patch
14+
- type: perf
15+
release: patch
16+
- type: docs
17+
release: patch
18+
- type: refactor
19+
release: patch
20+
- type: style
21+
release: patch
22+
- type: ci
23+
release: patch
24+
- type: build
25+
release: patch
26+
- type: chore
27+
release: patch
28+
- type: test
29+
release: patch
30+
31+
- - "@semantic-release/release-notes-generator"
32+
- preset: conventionalcommits
33+
presetConfig:
34+
types:
35+
- type: feat
36+
section: "Features"
37+
hidden: false
38+
- type: fix
39+
section: "Bug Fixes"
40+
hidden: false
41+
- type: perf
42+
section: "Performance"
43+
hidden: false
44+
- type: docs
45+
section: "Documentation"
46+
hidden: false
47+
- type: refactor
48+
section: "Refactoring"
49+
hidden: false
50+
- type: style
51+
section: "Style"
52+
hidden: false
53+
- type: ci
54+
section: "CI/CD"
55+
hidden: false
56+
- type: build
57+
section: "Build"
58+
hidden: false
59+
- type: chore
60+
section: "Chores"
61+
hidden: false
62+
- type: test
63+
section: "Tests"
64+
hidden: false
65+
66+
- - "@semantic-release/exec"
67+
- prepareCmd: "sed -i 's/^version = .*$/version = \"${nextRelease.version}\"/' pyproject.toml"
68+
69+
- - "@semantic-release/github"
70+
- releaseNameTemplate: "Version ${nextRelease.version}"
71+
72+
- - "@semantic-release/git"
73+
- assets:
74+
- pyproject.toml
75+
message: "chore(release): ${nextRelease.version}"
76+
77+
repositoryUrl: "https://github.com/mloda-ai/mloda-plugin-template"

‎AGENTS.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# AGENTS.md
2+
3+
This file provides guidance to Claude Code when working with this repository.
4+
5+
**Required reading:** Must start by reading [README.md](README.md) for project overview, structure, key files, and common tasks.

‎CLAUDE.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# CLAUDE.md
2+
3+
Must follow [AGENTS.md](AGENTS.md) for AI guidance and documentation links.

‎README.md‎

Lines changed: 135 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,135 @@
1-
# mloda-plugin-template
1+
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/mloda-ai/mloda-plugin-template/blob/main/LICENSE)
2+
[![mloda](https://img.shields.io/badge/built%20with-mloda-blue.svg)](https://github.com/mloda-ai/mloda)
3+
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
4+
5+
# mloda-plugin-template
6+
7+
> **A GitHub template for creating standalone mloda plugins.** Part of the [mloda](https://github.com/mloda-ai/mloda) ecosystem for open data access. Visit [mloda.ai](https://mloda.ai) for an overview and business context, the [GitHub repository](https://github.com/mloda-ai/mloda) for technical context, or the [documentation](https://mloda-ai.github.io/mloda/) for detailed guides.
8+
9+
Create your own FeatureGroups, ComputeFrameworks, and Extenders as standalone packages. See the [Getting Started guide](docs/getting-started.md) to create your repository, then follow the setup steps below.
10+
11+
## Related Repositories
12+
13+
- **[mloda](https://github.com/mloda-ai/mloda)**: The core library for open data access. Declaratively define what data you need, not how to get it. mloda handles feature resolution, dependency management, and compute framework abstraction automatically.
14+
15+
- **[mloda-registry](https://github.com/mloda-ai/mloda-registry)**: The central hub for discovering and sharing mloda plugins. Browse community-contributed FeatureGroups, find integration guides, and publish your own plugins for others to use.
16+
17+
## Structure
18+
19+
```
20+
placeholder/
21+
├── feature_groups/
22+
│ └── my_plugin/
23+
│ ├── __init__.py # Package exports
24+
│ ├── my_feature_group.py # Example FeatureGroup implementation
25+
│ └── tests/
26+
│ └── test_my_feature_group.py
27+
├── compute_frameworks/
28+
│ └── my_framework/
29+
│ ├── __init__.py
30+
│ └── my_compute_framework.py
31+
└── extenders/
32+
└── my_extender/
33+
├── __init__.py
34+
└── my_extender.py
35+
```
36+
37+
## Key Files
38+
39+
- `placeholder/` - Root namespace (users rename to company name)
40+
- `pyproject.toml` - Package config (users edit directly, not auto-generated)
41+
- `.github/workflows/test.yml` - CI workflow running pytest
42+
43+
## Common Tasks
44+
45+
### Setup Your Plugin
46+
47+
Follow these steps to customize the template for your organization:
48+
49+
#### 1. Rename the directory
50+
51+
```bash
52+
mv placeholder acme
53+
```
54+
55+
#### 2. Update pyproject.toml
56+
57+
Edit the following fields in `pyproject.toml`:
58+
59+
- `name`: Change `"placeholder-my-plugin"` to `"acme-my-plugin"`
60+
- `authors`: Update name and email
61+
- `description`: Update to describe your plugin
62+
- `tool.setuptools.packages.find.include`: Change `["placeholder*"]` to `["acme*"]`
63+
- `tool.pytest.ini_options.testpaths`: Change `["placeholder", "tests"]` to `["acme", "tests"]`
64+
65+
#### 3. Update Python imports
66+
67+
Update imports in these files (change `from placeholder.` to `from acme.`):
68+
69+
- `acme/feature_groups/my_plugin/__init__.py`
70+
- `acme/feature_groups/my_plugin/tests/test_my_feature_group.py`
71+
- `acme/compute_frameworks/my_plugin/__init__.py`
72+
- `acme/compute_frameworks/my_plugin/tests/test_my_compute_framework.py`
73+
- `acme/extenders/my_plugin/__init__.py`
74+
- `acme/extenders/my_plugin/tests/test_my_extender.py`
75+
76+
#### 4. Verify setup
77+
78+
```bash
79+
uv venv && source .venv/bin/activate && uv pip install -e ".[dev]" && tox
80+
```
81+
82+
### Development Setup with uv
83+
84+
**Install uv** (if not already installed):
85+
```bash
86+
curl -LsSf https://astral.sh/uv/install.sh | sh
87+
```
88+
89+
**Create virtual environment and install dependencies:**
90+
```bash
91+
uv venv
92+
source .venv/bin/activate
93+
uv pip install -e ".[dev]"
94+
```
95+
96+
**Run all checks with tox:**
97+
```bash
98+
# Install tox with uv backend
99+
uv tool install tox --with tox-uv
100+
101+
# Run all checks (pytest, ruff, mypy, bandit)
102+
tox
103+
```
104+
105+
### Run individual checks
106+
107+
```bash
108+
# Tests only
109+
pytest
110+
111+
# Format check
112+
ruff format --check --line-length 120 .
113+
114+
# Lint check
115+
ruff check .
116+
117+
# Type check
118+
mypy --strict --ignore-missing-imports .
119+
120+
# Security check
121+
bandit -c pyproject.toml -r -q .
122+
```
123+
124+
### Add new FeatureGroup
125+
Create new directory under `placeholder/feature_groups/` following the `my_plugin/` pattern.
126+
127+
## Related Documentation
128+
129+
Guides for plugin development can be found in mloda-registry:
130+
131+
- https://github.com/mloda-ai/mloda-registry/tree/main/docs/guides/
132+
133+
## Architecture Overview
134+
135+
- [Repository structure and relationships](https://github.com/mloda-ai/mloda-registry/blob/main/docs/architecture/00_repositories.md)

‎docs/getting-started.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Getting Started
2+
3+
There are two ways to create your own mloda plugin from this template.
4+
5+
## Option 1: Use as Template (Recommended)
6+
7+
GitHub's template feature creates a new repository with all files but a clean commit history.
8+
9+
1. Click the green **"Use this template"** button on the [repository page](https://github.com/mloda-ai/mloda-plugin-template)
10+
2. Choose **"Create a new repository"**
11+
3. Name your repository (e.g., `acme-features`, `acme-data-plugins`, or `mycompany-feature-groups`)
12+
13+
> **Note:** Please don't use "mloda" in your package or repository name. However, you can use formulations like "for mloda" or "mloda-compatible" in descriptions.
14+
15+
4. Choose public or private visibility
16+
5. Click **"Create repository"**
17+
18+
**Advantages:**
19+
- Clean commit history (starts fresh)
20+
- No fork relationship to maintain
21+
- Your repo is completely independent
22+
- One-click setup in GitHub UI
23+
24+
## Option 2: Fork
25+
26+
Forking creates a copy that maintains a connection to the original repository.
27+
28+
1. Click the **"Fork"** button on the [repository page](https://github.com/mloda-ai/mloda-plugin-template)
29+
2. Choose your account or organization
30+
3. Name your forked repository
31+
4. Click **"Create fork"**
32+
33+
**Advantages:**
34+
- Can pull updates from the original template
35+
- Familiar workflow for open source contributors
36+
37+
**Disadvantages:**
38+
- Maintains fork relationship (shows "forked from" on your repo)
39+
- Copies entire commit history
40+
- GitHub may suggest contributing back to the original
41+
42+
## After Creating Your Repository
43+
44+
Regardless of which option you chose, follow the setup steps in the [README](../README.md#setup-your-plugin) to customize the template:
45+
46+
1. Clone your new repository locally
47+
2. Rename the `placeholder/` directory
48+
3. Update `pyproject.toml`
49+
4. Update Python imports
50+
5. Verify with `tox`

‎placeholder/__init__.py‎

Whitespace-only changes.

‎placeholder/compute_frameworks/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
"""Compute frameworks namespace package."""

0 commit comments

Comments
 (0)