# Commit Message Instructions for GitHub Copilot

## Format Structure

Follow the **Conventional Commits** format:

```
<type>(<scope>): <description>
```

For breaking changes:

```
BREAKING(<scope>): <description>
```

If multiple changes are included in one commit, put the most important change in the summary line. And list other changes in the commit body using bullet points.

```
<type>(<scope>): <description>

- <other change 1>
- <other change 2>
```

## Commit Types

Use these types in order of frequency and priority:

- **fix**: Bug fixes and corrections
- **feat**: New features or functionality
- **chore**: Maintenance tasks (dependency updates, configuration changes)
- **docs**: Documentation improvements
- **ci**: CI/CD configuration changes
- **test**: Test additions or modifications
- **refactor**: Code restructuring without behavior changes
- **enh**: Enhancements to existing features
- **style**: Code formatting and style changes
- **BREAKING**: Breaking changes (prefix before other types)

## Scope Guidelines

### Module/Namespace Names
- `scrna`: Single-cell RNA-seq processes
- `tcr`: T-cell receptor analysis
- `bam`: BAM file operations
- `cnv`: Copy number variation
- `cnvkit`: CNVkit-related processes
- `vcf`: VCF file operations
- `bed`: BED file operations
- `regulatory`: Regulatory analysis
- `stats`: Statistical analysis
- `plot`: Plotting utilities
- `delim`: Delimited file operations
- `gene`: Gene-related operations
- `gsea`: Gene set enrichment analysis
- `misc`: Miscellaneous utilities
- `protein`: Protein analysis
- `rnaseq`: RNA-seq analysis
- `snp`: SNP analysis
- `web`: Web-related utilities
- `utils`: Utility functions

### Specific Process Names
Use the full process class name when the change is specific to that process:
- `SeuratPreparing`, `MarkersFinder`, `SeuratClusterStats`, `SeuratClustering`
- `CellTypeAnnotation`, `ModuleScoreCalculator`, `CellCellCommunication`
- `ImmunarchLoading`, `ClonalStats`, `TCRClustering`, `TESSA`
- `MetabolicFeatures`, `MetabolicPathwayActivity`, `MetabolicPathwayHeterogeneity`

### Special Scopes
- `deps`: Dependency updates
- `docker`: Docker-related changes
- `ci`: CI/CD changes (can also be used as type)
- Omit scope for project-wide changes

## Description Style

### General Rules
1. **Start with lowercase** (unless it's a proper noun or acronym)
2. **Use imperative mood**: "add" not "added", "fix" not "fixes", "update" not "updated"
3. **Be specific and descriptive**: Include what changed and why
4. **Include context** when fixing bugs (e.g., "due to upgrade to ggplot2 v4")
5. **Reference issues** when applicable: `(#123)` or `(pwwang/immunopipe#45)`
6. **No period** at the end of the description

### Specific Patterns

**For bug fixes:**
- Include the problem being solved
- Mention the cause if known
- Examples:
  - `fix(scrna.MarkersFinder): improve marker processing and enrichment checks when result has no markers/enrichments`
  - `fix(scrna.SeuratClusterStats): improve error handling in feature plotting when save_code (due to upgrade to ggplot2 v4)`
  - `fix(tcr.ScRepLoading): fix an issue where barcode is not the first column when loaded for 10X data`

**For new features:**
- Describe what capability is being added
- Examples:
  - `feat(scrna.MarkersFinder): allow using other metadata columns from object for enrichment plot of all subcases`
  - `feat(scrna.ModuleScoreCalculator): add post mutaters functionality to allow compound modules based on added modules`
  - `feat(regulatory.MotifAffinityTest): add variant column support in MotifAffinityTest so only paired variant-motif can be output`

**For documentation:**
- Be specific about what documentation changed
- Examples:
  - `docs(scrna.SeuratPreparing): enhance cell_qc parameter description in SeuratPreparing`
  - `docs(tcr.ClonalStats): add example configurations and plots`
  - `docs(scrna.MarkersFinder): correct URL in documentation`

**For dependency updates:**
- Include version numbers when bumping specific packages
- Examples:
  - `chore(deps): bump pipen to 0.17.21`
  - `chore(deps): update dependencies`
  - `chore(deps): bump pipen-report to 0.23.8`

**For chores:**
- Be clear about what maintenance task was performed
- Examples:
  - `chore(scrna.SeuratClusterStats): adjust plot settings for better visualization`
  - `chore(docker): add procps-ng for free command for pipen-runinfo`
  - `chore: update Dockerfiles to use multi-stage building`

**For CI/CD:**
- Describe what aspect of CI/CD changed
- Examples:
  - `ci: update cache number for conda environments to force updates`
  - `ci(docker): update Dockerfiles to use dynamic REF_NAME argument`
  - `ci: correct condition for deleting old test intermediate cache`

**For tests:**
- Mention what is being tested or how tests changed
- Examples:
  - `test(scrna): add set.seed to PrepareSeurat script`
  - `test(cellranger): add tests for CellRangerCount and CellRangerSummary with data download setup`
  - `test(scrna): merge tests for Seurat processes to avoid repeatedly load pbmc3k dataset`

**For refactoring:**
- Mention what is being restructured
- Examples:
  - `refactor(scrna.CellCellCommunicationPlots): use scplotter::CCCPlot`
  - `refactor(tcr.CDR3AAPhyschem): adopt input from ScRepCombiningExpression`
  - `refactor: remove utility R scripts and use biopipen.utils.R package`

**For breaking changes:**
- Clearly state what is breaking and what replaces it
- Examples:
  - `BREAKING(scrna.MetabolicFeatures): use ':' instead of ',' to separate groups for comparisons`
  - `BREAKING: merge namespace bcftools to vcf`

**For enhancements:**
- Describe the improvement being made
- Examples:
  - `enh(bam.CNAClinic): change envs.binsize to bp instead of kbp`
  - `enh(cnv): replace ggplot2 with plotthis for improved plotting in AneuploidyScoreSummary and TMADScoreSummary`
  - `enh(scrna_metabolic_landscape): improve flexibility and stability of metabolic landscape analysis`

## Common Verbs to Use

- **add**: Adding new files, features, tests, dependencies
- **fix**: Fixing bugs, errors, issues
- **update**: Updating existing functionality, documentation, dependencies
- **remove**: Removing files, features, code
- **refactor**: Restructuring code
- **improve**: Making existing functionality better
- **enhance**: Adding improvements to existing features
- **correct**: Fixing typos, incorrect values
- **rename**: Renaming variables, files, functions
- **replace**: Replacing one thing with another
- **bump**: Updating dependency versions
- **allow**: Enabling new capabilities
- **support**: Adding support for something
- **ensure**: Making sure something works correctly
- **handle**: Dealing with specific cases or errors
- **adopt**: Using a new approach or library
- **adjust**: Fine-tuning settings or parameters

## Multi-Change Commits

When a release includes multiple related changes, group them by category:

### Major Releases Structure
```markdown
### New Features
- feat(...): ...
- feat(...): ...

### Enhancements
- enh(...): ...
- enh(...): ...

### Bug Fixes
- fix(...): ...
- fix(...): ...

### Refactoring
- refactor(...): ...
- refactor(...): ...

### Development & Infrastructure
- chore(deps): ...
- chore(docker): ...
- test(...): ...
- ci: ...
```

## Examples by Category

### Bug Fixes
```
fix(scrna.MarkersFinder): improve marker processing and enrichment checks when result has no markers/enrichments
fix(web.Download): improve URL handling in output filename generation
fix(tcr.ClonalStats): replace deprecated ClonalDynamicsPlot with ClonalStatPlot
fix(scrna.CellTypeAnnotation): fix identification of default ident if rds or qs is given as input for celltypist
fix(scrna.SeuratClusterStats): correct typo in group_by variable name
```

### New Features
```
feat(scrna.SeuratPreparing): allow seurat object as input
feat(scrna.MarkersFinder): allow using other metadata columns from object for enrichment plot of all subcases
feat(scrna.ModuleScoreCalculator): add post mutaters functionality to allow compound modules based on added modules
feat(scrna.CellTypeAnnotation): add support for additional direct cell type annotations
feat(tcr.ScRepCombiningExpression): add TCR presence indicator to combined expression object
```

### Documentation
```
docs(scrna.SeuratPreparing): improve documentation for SeuratPreparing to make sure new lines in code blocks
docs(scrna.SeuratClusterStats): enhance documentation for cluster statistics plots
docs(tcr.ClonalStats): add example configurations and plots
docs(scrna.ScFGSEA): add examples and usage details for GSEA plots
docs(scrna.ModuleScoreCalculator): update link format in ModuleScoreCalculator docstring
```

### Chores
```
chore: bump pipen to 0.17.21
chore(deps): update dependencies
chore: update Dockerfiles to use multi-stage building
chore(scrna.SeuratClusterStats): adjust plot settings for better visualization
chore(ci): change CACHE_NUMBER for conda environment to ensure latest biopipen.utils.R is installed
```

### CI/CD
```
ci: update CACHE_NUMBER for conda environment to force install latest dependencies
ci: correct condition for deleting old test intermediate cache
ci(docker): update Dockerfiles to use dynamic REF_NAME argument
ci: update build condition and add caching for test intermediates
ci: add caching for conda environments to improve workflow efficiency
```

### Tests
```
test(scrna): add set.seed to PrepareSeurat script
test(scrna): merge tests for Seurat processes to avoid repeatedly load pbmc3k dataset
test(cellranger): add tests for CellRangerCount and CellRangerSummary with data download setup
test: improve test output grouping for better readability
```

### Refactoring
```
refactor(scrna.CellCellCommunicationPlots): use scplotter::CCCPlot
refactor(tcr.CDR3AAPhyschem): adopt input from ScRepCombiningExpression
refactor: remove utility R scripts and use biopipen.utils.R package
```

### Breaking Changes
```
BREAKING(scrna.MetabolicFeatures): use ':' instead of ',' to separate groups for comparisons
BREAKING: merge namespace bcftools to vcf
```

### Enhancements
```
enh(bam.CNAClinic): change envs.binsize to bp instead of kbp
enh(cnv): replace ggplot2 with plotthis for improved plotting in AneuploidyScoreSummary and TMADScoreSummary
enh(scrna_metabolic_landscape): improve flexibility and stability of metabolic landscape analysis
```

## Special Conventions

### Parameter Renames
```
chore(tcr.ScRepCombiningExpression): rename TCR_presence to VDJ_presence in metadata of output Seurat object
```

### Deprecation Fixes
```
fix(tcr.ClonalStats): replace deprecated ClonalDynamicsPlot with ClonalStatPlot
```

### Version-Specific Fixes
```
fix(scrna.SeuratClusterStats): improve error handling in feature plotting when save_code (due to upgrade to ggplot2 v4)
```

### Issue References
```
docs: improve documentation for SeuratPreparing to make sure new line… (#180)
chore: add descriptive summaries for fgsea and enrichr results (#158)
```

## Tips for Writing Good Commit Messages

1. **Be atomic**: Each commit should represent one logical change
2. **Be descriptive**: Someone reading the message should understand what changed without looking at the code
3. **Add context**: Explain why the change was needed, especially for bug fixes
4. **Use the scope**: It helps organize changes and makes them searchable
5. **Think about the changelog**: Your commit message will appear in the release notes
6. **Be consistent**: Follow these conventions for all commits

## What NOT to Do

❌ `fix: bug fix`
✅ `fix(scrna.MarkersFinder): improve marker processing when result has no markers`

❌ `update code`
✅ `refactor(scrna.CellCellCommunicationPlots): use scplotter::CCCPlot`

❌ `Fixed the issue`
✅ `fix(tcr.ScRepLoading): fix an issue where barcode is not the first column when loaded for 10X data`

❌ `feat: new feature`
✅ `feat(scrna.SeuratPreparing): allow seurat object as input`

❌ `Updated dependencies`
✅ `chore(deps): bump pipen to 0.17.21`
