research-publishing

# Research Publishing Methodology

You are helping a researcher prepare their code and artifacts for public release alongside a paper submission.

## Step 1: Repository Assessment

Before any changes, audit the current state:

1. **Sensitive content scan**:
   - API keys, tokens, credentials (grep for common patterns)
   - Hardcoded paths specific to the researcher's machine
   - Internal URLs or private infrastructure references
   - Personal identifiable information in comments or data

2. **Dependency audit**:
   - List all dependencies with pinned versions
   - Identify any proprietary or restricted-license dependencies
   - Check for abandoned/unmaintained dependencies
   - Verify all dependencies are pip/conda installable

3. **Code organization**:
   - Identify dead code, debugging artifacts, scratch files
   - Find duplicated code that should be unified
   - Check for overly complex code that can be simplified

## Step 2: Repository Structure

A publishable research repository should have:

```
project/
  README.md            # Installation, usage, citation
  LICENSE              # Must have an explicit license
  requirements.txt     # or pyproject.toml with pinned deps
  setup.py / setup.cfg # Package installation
  src/                 # Source code
  scripts/             # Training, evaluation, inference scripts
  configs/             # Configuration files
  data/                # Sample data or download instructions
  checkpoints/         # Download instructions (not actual weights)
  results/             # Key result files referenced in paper
```

## Step 3: Reproducibility Checklist

For each experiment in the paper:

- [ ] Configuration file exists and matches paper's hyperparameters
- [ ] Random seeds are set and documented
- [ ] Training command is documented end-to-end
- [ ] Evaluation command produces the reported numbers
- [ ] Data preprocessing steps are scripted (not manual)
- [ ] Hardware requirements are documented (GPU type, memory, time)
- [ ] Dependencies are version-pinned

## Step 4: README Structure

A research README must include:

1. **Title + one-line description**
2. **Paper link** (arXiv, venue page)
3. **Visual** (architecture diagram, key result figure, or demo GIF)
4. **Installation** (step-by-step, tested on clean environment)
5. **Quick start** (inference on a single example, < 5 commands)
6. **Training** (full reproduction commands)
7. **Evaluation** (reproduce paper numbers)
8. **Model zoo / checkpoints** (download links with expected metrics)
9. **Citation** (BibTeX block)
10. **License**

## Step 5: Code Cleanup

Apply minimal, targeted cleanup:

1. **Remove** debugging prints, commented-out code, scratch experiments
2. **Replace** hardcoded paths with configurable paths (env vars or args)
3. **Add** docstrings to public functions (not internal helpers)
4. **Ensure** the main entry points are clearly documented
5. **Do NOT** refactor working code for style — it adds risk for no benefit

## Step 6: License Selection

Guide the user through license choice:

| License | Allows commercial use | Requires attribution | Copyleft |
|---------|----------------------|---------------------|----------|
| MIT | Yes | Yes | No |
| Apache 2.0 | Yes | Yes | No (patent grant) |
| GPL 3.0 | Yes | Yes | Yes (derivative works) |
| CC BY 4.0 | Yes | Yes | No (for non-code) |
| CC BY-NC 4.0 | No | Yes | No (for non-code) |

Default recommendation: MIT for code, CC BY 4.0 for datasets/models.

## Step 7: Pre-Release Testing

Before publishing:

1. Clone into a fresh directory
2. Follow README installation steps exactly
3. Run quick start commands
4. Run evaluation to verify numbers match paper
5. Check that no sensitive information is in git history

## Output Format

Produce:
1. **Audit report**: sensitive content found, dependency issues, dead code
2. **Action list**: specific files to modify/remove/add
3. **README draft**: following the structure above
4. **Reproducibility checklist**: per-experiment verification status