Skip to content

getting-started.md

Latest commit

 

History

History
62 lines (45 loc) · 2.82 KB

getting-started.md

File metadata and controls

62 lines (45 loc) · 2.82 KB
Raw

Getting Started

There are two ways to create your own mloda plugin from this template.

Option 1: Use as Template (Recommended)

GitHub's template feature creates a new repository with all files but a clean commit history.

  1. Click the green "Use this template" button on the repository page

  2. Choose "Create a new repository"

  3. Name your repository (e.g., acme-features, acme-data-plugins, or mycompany-feature-groups)

    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.

  4. Choose public or private visibility

  5. Click "Create repository"

Advantages:

  • Clean commit history (starts fresh)
  • No fork relationship to maintain
  • Your repo is completely independent
  • One-click setup in GitHub UI

Option 2: Fork

Forking creates a copy that maintains a connection to the original repository.

  1. Click the "Fork" button on the repository page
  2. Choose your account or organization
  3. Name your forked repository
  4. Click "Create fork"

Advantages:

  • Can pull updates from the original template
  • Familiar workflow for open source contributors

Disadvantages:

  • Maintains fork relationship (shows "forked from" on your repo)
  • Copies entire commit history
  • GitHub may suggest contributing back to the original

After Creating Your Repository

Regardless of which option you chose, follow the setup steps in the README to customize the template:

  1. Clone your new repository locally
  2. Rename the placeholder/ directory
  3. Update pyproject.toml
  4. Update .releaserc.yaml (change mloda-plugin-template to your package name and update repositoryUrl)
  5. Update Python imports
  6. Verify with tox
  7. Remove CONTRIBUTING.md — it describes contributing to the template repo, not your plugin
  8. Keep CODE_OF_CONDUCT.md, AGENTS.md, CLAUDE.md, and .github/ISSUE_TEMPLATE/ as inherited baselines; tune them later (contact email, placeholder paths, toolchain bullets) if you want
  9. Configure repository settings on GitHub: see github-repository-settings.md for the secrets, branch protection, required checks, and dependabot reviewer that the inherited workflows expect

Plugin discovery

Once installed, your plugins are auto-discovered by mloda through entry points, so users reach them via PluginLoader.all() with no manual import. customize.sh rewrites the [project.entry-points."mloda.*"] manifest paths for you. When you add plugins, append the class to the matching manifest.py list; see Plugin discovery for the resilient-import caveat when a plugin needs an optional backend.