Roadmap · Project hygiene · P1 · S

Lead the README with `pip install modulearn`

A build-it-yourself guide. The README's install block still opens with the contributor path, pip install -e .. But ModuLearn ships on PyPI now — the first command a reader copies should be the one that works for them, not the one that only works if they cloned the repo.

Done when: the top of the README installs from PyPI (pip install modulearn), the editable/from-source path is kept but demoted to a contributor note, and every command in the block still runs verbatim.

0 / 0 steps

← roadmap single-source version → changelog + tags → CI badge →

The gotcha

A reader skims the first code block and pastes it. If that block says pip install -e ., it fails for anyone who hasn't cloned the repo — the exact person a README is written for. -e . is a maintainer workflow (editable install from a checkout); the user workflow is pip install modulearn. Lead with the user's.

Don't delete the source path — demote it. Contributors still need pip install -e ".[dev]". Keep it, but below the fold, clearly labelled as the from-source route so nobody mistakes it for the default.

Steps

Rewrite the install block to lead with PyPI

README.md — the ## Install section

Swap the first fenced block so the PyPI one-liner is the first thing a reader copies.

## Install

```bash
pip install modulearn      # fastapi + uvicorn + pydantic, from PyPI
modulearn demo             # serve the bundled editor at http://localhost:8000
```

Keep the from-source path as a contributor note

README.md — just under the install block, or in a Contributing section
Preserve the editable install for people hacking on ModuLearn itself — labelled so it reads as the contributor route, not the default.
```
> **Working on ModuLearn itself?** Clone the repo and install editable with the
> dev extras: `pip install -e ".[dev]"` (adds pytest, build, twine).
```
Sanity-check the surrounding prose

README.md — the lines after the block

The paragraph about modulearn demo being dependency-free and the modulearn run examples are still accurate — just confirm nothing else references -e . as the primary install. The modulearn init command is now the fastest way to start a real project, so it's worth a mention here too.
Verify the commands actually work from PyPI
Prove the copied path works in a clean environment — the whole point of the change.
```
python -m venv /tmp/pypi-check && source /tmp/pypi-check/bin/activate
pip install modulearn          # the exact line the README now leads with
modulearn --version            # expect: modulearn 0.2.0
modulearn demo                 # opens http://localhost:8000
deactivate
```
Match the version to what's live. If pip install modulearn pulls an older release than the repo, that's the changelog + tags task calling — cut the release first so the README doesn't promise a version PyPI can't serve.

Commit

git add README.md
git commit -m "README: lead install with pip install modulearn"
git push
gh run list --branch main --limit 1   # expect: success

Mark it shipped on the roadmap

Add done:true, to the {area:"hygiene", … title:"Lead the README with pip install modulearn"} item in docs/roadmap.html.

Worth knowing

The README is the package's front door. PyPI renders it verbatim on the project page, so the very first block there is what a stranger evaluating ModuLearn sees. Leading with the working one-liner is the cheapest credibility win in this whole section.