15. Open-Source Release

Chapter 15 of 18 · 20 min

KEY INSIGHT

Releasing code is not the same as enabling reproduction. Code without environment specification, usage examples, and maintenance is a liability for both users and authors. Open-sourcing your research system extends its impact beyond readers who can reconstruct your work from paper descriptions. However, sloppy releases create more problems than they prevent. ### What to Release **Core implementation**: The code that produces your results. Clean it enough for others to read, but don't over-abstract—readability matters more than elegance in research code. **Evaluation scripts**: The exact commands used to generate your benchmark numbers. Reproducibility requires more than "run the evaluation script"—include the exact parameters, seeds, and environment. **Trained models/weights**: If feasible. Large models may be too big for standard hosting, but consider model cards and pointers to external hosting. **Data splits**: The exact train/validation/test splits, especially if you're releasing a new benchmark. Without the splits, others cannot reproduce your evaluation. ```python # release_checklist.py RELEASE_CHECKLIST = """ [ ] Code runs without modifications on a fresh environment [ ] All dependencies specified with versions [ ] README with: [ ] Installation instructions [ ] Quick start example [ ] Expected hardware requirements [ ] License [ ] Evaluation reproduces claimed results [ ] Known limitations documented [ ] Issues or PRs monitored and responded to [ ] Model card (if releasing models) """ ``` ### Repository Structure ``` research-system/ ├── README.md # Overview, quick start ├── LICENSE # AGPL-3.0, MIT, Apache 2.0 ├── requirements.txt # Exact dependencies ├── setup.py # Installation ├── docs/ # Full documentation │ ├── getting_started.md │ ├── api_reference.md │ └── evaluation.md ├── src/ # Source code │ └── research_system/ ├── examples/ # Usage examples ├── scripts/ # Evaluation and training scripts ├── configs/ # Default configurations └── tests/ # Unit tests ``` ### License Selection Choose a license appropriate for your goals: - **MIT/Apache 2.0**: Permissive, maximizes adoption. Good for tools others will incorporate into larger projects. - **GPL-3.0**: Requires derivative works to be open source. Good if you want to prevent proprietary competition. - **CC BY 4.0**: For documentation and model cards, not code. AGPL-3.0 is increasingly common for AI systems—it's GPL but covers network use, important for hosted services. ### Maintenance Expectations Open-source comes with obligations. Before releasing, decide: - Will you respond to issues and PRs? On what timeline? - Will you accept external contributions? - Will you maintain compatibility across versions? Being clear about limitations ("this is a research release, not production-ready") manages expectations and reduces support burden.

EXERCISE

Prepare your research system for open-source release. Create a repository structure, write a README with installation and quick-start instructions, and document three known limitations. Ask a colleague to follow your instructions from scratch without asking questions—note where they got stuck.