documentation-and-metadata-modernization
Summary
Audit and adapt a scientific Python package's metadata, configuration files, and documentation to conform to organizational standards (e.g., metabolomics-cloud conventions) when relocating to a new GitHub organization. This ensures consistent project structure, CI/CD workflows, and installation behavior across a federated codebase.
When to use
A mature scientific package (e.g., Mummichog 3) is being migrated to a new GitHub organization that enforces standardized project structure, and the current setup.py, pyproject.toml, requirements.txt, .github workflows, and module naming do not yet conform to the target organization's conventions.
When NOT to use
- The package is a one-off analysis script with no installation infrastructure (setup.py, pyproject.toml) — documentation modernization assumes a distributable package.
- The target organization has not published explicit standards or exemplar projects to audit against — without reference conventions, conformance cannot be assessed.
- The package is already installed and in active use by downstream projects; migration risk may outweigh standardization benefits without a staged rollout plan.
Inputs
- Current package repository (source code, setup.py, pyproject.toml, requirements.txt, .github/workflows)
- Target organization's standards documentation or exemplar repositories (e.g., scverse.org projects)
- Representative metabolomics test data (feature table TSV, annotation JSON, metabolic model JSON)
Outputs
- Migrated repository under target organization (e.g., metabolomics-cloud/mummichog)
- Updated package metadata and configuration files conforming to organizational standards
- Installation verification report (pip install success, no build errors)
- Functional verification report (core workflows execute correctly on test data)
- Migration summary documenting all conformance changes and validation results
How to apply
Begin by cloning the current repository and auditing its structure against the target organization's standards, documenting differences in package metadata, module naming, documentation layout, and CI/CD workflows. Systematically adapt configuration files (setup.py, pyproject.toml, requirements.txt) and .github action workflows to match organizational conventions. Create a new repository under the target organization with the migrated codebase and updated metadata. Verify the migration by running installation tests in a clean environment (e.g., pip install in a virtualenv) to ensure the package builds without errors. Execute core functionality tests on representative data (e.g., loading feature tables and running functional prediction workflows) to confirm runtime correctness. Finally, validate that all unit tests pass and generate a migration report documenting all conformance changes and verification results.
Related tools
- Python setuptools / pyproject.toml (Define package metadata, dependencies, and build configuration for standardized installation)
- GitHub Actions / .github/workflows (Implement organization-standard CI/CD workflows for testing and validation on migration) — https://github.com/metabolomics-cloud/mummichog
- virtualenv (Create isolated Python environments to verify clean installation without dependency conflicts)
- scverse.org project structure (Reference exemplar for organizing modular scientific Python packages in federated organizations) — https://scverse.org/
Examples
python3 -m mummichog.main -i tests/ineurons_ttest_1127.tsv -j testneuron -a tests/empCpds_with_annotations.json -d .
Evaluation signals
- pip install succeeds in a clean virtualenv without build errors or dependency resolution failures
- Core Mummichog workflows (feature table loading, functional prediction on representative metabolomics data) execute without runtime errors
- All existing unit tests pass in the migrated repository
- Package metadata (name, version, author, dependencies) is consistent across setup.py, pyproject.toml, and README
- Documentation structure and .github workflow files match target organization's exemplar repositories (e.g., scverse.org standards)
Limitations
- Migration report assumes target organization standards are explicit and documented; ad-hoc or unstated conventions will require manual interpretation.
- Testing may be incomplete if representative metabolomics test data is unavailable; functional verification relies on test dataset representativeness.
- Backward compatibility with v2.7 (mummichog-2.7 branch) is not verified in the migration workflow; deprecated APIs or breaking changes may emerge.
- No changelog was found in the source material; migration changes should be documented explicitly to inform users of v2 → v3 differences.
Evidence
- [other] Clone the current Mummichog 3 repository and audit its structure, dependencies, and configuration files (setup.py, pyproject.toml, requirements.txt, .github workflows) against metabolomics-cloud organization standards.: "Clone the current Mummichog 3 repository and audit its structure, dependencies, and configuration files (setup.py, pyproject.toml, requirements.txt, .github workflows) against metabolomics-cloud"
- [other] Adapt package metadata, module naming, documentation structure, and CI/CD workflows to conform to metabolomics-cloud conventions.: "Adapt package metadata, module naming, documentation structure, and CI/CD workflows to conform to metabolomics-cloud conventions."
- [other] Run installation tests in a clean environment using pip install to verify the package builds without errors.: "Run installation tests in a clean environment using pip install to verify the package builds without errors."
- [other] Execute core Mummichog functionality (e.g., loading feature tables and running functional prediction workflows) to confirm runtime correctness on representative metabolomics data.: "Execute core Mummichog functionality (e.g., loading feature tables and running functional prediction workflows) to confirm runtime correctness on representative metabolomics data."
- [readme] Project is moved to new organization https://github.com/metabolomics-cloud, to follow examples of https://scverse.org/: "Project is moved to new organization https://github.com/metabolomics-cloud, to follow examples of https://scverse.org/"
- [readme] Let's keep this as core package, with minimal dependency.: "Let's keep this as core package, with minimal dependency."
1---2name: documentation-and-metadata-modernization3description: Use when a mature scientific package (e.g., Mummichog 3) is being migrated to a new GitHub organization that enforces standardized project structure, and the current setup.py, pyproject.toml, requirements.txt, .4license: CC-BY-4.05---67# documentation-and-metadata-modernization89## Summary1011Audit and adapt a scientific Python package's metadata, configuration files, and documentation to conform to organizational standards (e.g., metabolomics-cloud conventions) when relocating to a new GitHub organization. This ensures consistent project structure, CI/CD workflows, and installation behavior across a federated codebase.1213## When to use1415A mature scientific package (e.g., Mummichog 3) is being migrated to a new GitHub organization that enforces standardized project structure, and the current setup.py, pyproject.toml, requirements.txt, .github workflows, and module naming do not yet conform to the target organization's conventions.1617## When NOT to use1819- The package is a one-off analysis script with no installation infrastructure (setup.py, pyproject.toml) — documentation modernization assumes a distributable package.20- The target organization has not published explicit standards or exemplar projects to audit against — without reference conventions, conformance cannot be assessed.21- The package is already installed and in active use by downstream projects; migration risk may outweigh standardization benefits without a staged rollout plan.2223## Inputs2425- Current package repository (source code, setup.py, pyproject.toml, requirements.txt, .github/workflows)26- Target organization's standards documentation or exemplar repositories (e.g., scverse.org projects)27- Representative metabolomics test data (feature table TSV, annotation JSON, metabolic model JSON)2829## Outputs3031- Migrated repository under target organization (e.g., metabolomics-cloud/mummichog)32- Updated package metadata and configuration files conforming to organizational standards33- Installation verification report (pip install success, no build errors)34- Functional verification report (core workflows execute correctly on test data)35- Migration summary documenting all conformance changes and validation results3637## How to apply3839Begin by cloning the current repository and auditing its structure against the target organization's standards, documenting differences in package metadata, module naming, documentation layout, and CI/CD workflows. Systematically adapt configuration files (setup.py, pyproject.toml, requirements.txt) and .github action workflows to match organizational conventions. Create a new repository under the target organization with the migrated codebase and updated metadata. Verify the migration by running installation tests in a clean environment (e.g., pip install in a virtualenv) to ensure the package builds without errors. Execute core functionality tests on representative data (e.g., loading feature tables and running functional prediction workflows) to confirm runtime correctness. Finally, validate that all unit tests pass and generate a migration report documenting all conformance changes and verification results.4041## Related tools4243- **Python setuptools / pyproject.toml** (Define package metadata, dependencies, and build configuration for standardized installation)44- **GitHub Actions / .github/workflows** (Implement organization-standard CI/CD workflows for testing and validation on migration) — https://github.com/metabolomics-cloud/mummichog45- **virtualenv** (Create isolated Python environments to verify clean installation without dependency conflicts)46- **scverse.org project structure** (Reference exemplar for organizing modular scientific Python packages in federated organizations) — https://scverse.org/4748## Examples4950```51python3 -m mummichog.main -i tests/ineurons_ttest_1127.tsv -j testneuron -a tests/empCpds_with_annotations.json -d .52```5354## Evaluation signals5556- pip install succeeds in a clean virtualenv without build errors or dependency resolution failures57- Core Mummichog workflows (feature table loading, functional prediction on representative metabolomics data) execute without runtime errors58- All existing unit tests pass in the migrated repository59- Package metadata (name, version, author, dependencies) is consistent across setup.py, pyproject.toml, and README60- Documentation structure and .github workflow files match target organization's exemplar repositories (e.g., scverse.org standards)6162## Limitations6364- Migration report assumes target organization standards are explicit and documented; ad-hoc or unstated conventions will require manual interpretation.65- Testing may be incomplete if representative metabolomics test data is unavailable; functional verification relies on test dataset representativeness.66- Backward compatibility with v2.7 (mummichog-2.7 branch) is not verified in the migration workflow; deprecated APIs or breaking changes may emerge.67- No changelog was found in the source material; migration changes should be documented explicitly to inform users of v2 → v3 differences.6869## Evidence7071- [other] Clone the current Mummichog 3 repository and audit its structure, dependencies, and configuration files (setup.py, pyproject.toml, requirements.txt, .github workflows) against metabolomics-cloud organization standards.: "Clone the current Mummichog 3 repository and audit its structure, dependencies, and configuration files (setup.py, pyproject.toml, requirements.txt, .github workflows) against metabolomics-cloud"72- [other] Adapt package metadata, module naming, documentation structure, and CI/CD workflows to conform to metabolomics-cloud conventions.: "Adapt package metadata, module naming, documentation structure, and CI/CD workflows to conform to metabolomics-cloud conventions."73- [other] Run installation tests in a clean environment using pip install to verify the package builds without errors.: "Run installation tests in a clean environment using pip install to verify the package builds without errors."74- [other] Execute core Mummichog functionality (e.g., loading feature tables and running functional prediction workflows) to confirm runtime correctness on representative metabolomics data.: "Execute core Mummichog functionality (e.g., loading feature tables and running functional prediction workflows) to confirm runtime correctness on representative metabolomics data."75- [readme] Project is moved to new organization https://github.com/metabolomics-cloud, to follow examples of https://scverse.org/: "Project is moved to new organization https://github.com/metabolomics-cloud, to follow examples of https://scverse.org/"76- [readme] Let's keep this as core package, with minimal dependency.: "Let's keep this as core package, with minimal dependency."
HolobiomicsLab