Contributing to Gitignore Templates

Relevant source files

This document explains how to contribute new templates or update existing templates in the GitHub gitignore repository. It covers contribution guidelines, template quality standards, folder placement criteria, versioning strategies, and the submission workflow.

For detailed information about template structure and best practices, see Template Standards and Guidelines. For understanding the repository organization, see Repository Structure and Organization.

Purpose and Scope

The gitignore repository accepts contributions that provide value to the broader developer community. The contribution process ensures templates remain high-quality, well-documented, and appropriately categorized. This page documents the technical requirements, organizational decisions, and workflow mechanics for submitting changes.

Key Goals:

Maintain a curated collection of the most common and helpful templates.
Ensure contributions include sufficient documentation and justification.
Place templates in appropriate locations based on usage patterns.
Support version management for evolving technologies.

Template Placement Decision Tree

Sources: README.md19-35 README.md37-55 README.md71-82 README.md84-89

Contribution Workflow

Technical Implementation:

The workflow follows GitHub's standard fork-and-pull-request model README.md114-129:

Fork Project: Create a personal copy via the GitHub interface README.md118
Create Branch: Create a specific branch for the change README.md119
Modify Template: Make changes to the fork, ideally modifying only one template README.md120 CONTRIBUTING.md28-29
Open Pull Request: Send a PR from the fork's branch to the main branch README.md121

Sources: README.md114-129 CONTRIBUTING.md28-29

Contribution Guidelines Requirements

Requirement	Description	Rationale
Application Link	Provide homepage URL for language/framework/tool	Maintainers may not be familiar with the technology CONTRIBUTING.md7-9
Documentation Links	Include canonical documentation for ignored files	Current documentation is preferred over historical CONTRIBUTING.md17-18
Change Justification	Explain why the change applies to everyone	Distinguish universal patterns from team-specific preferences CONTRIBUTING.md11-15
Scope Consideration	Ensure changes target correct template	OS-specific rules like `.DS_Store` belong only in `Global/macOS.gitignore` CONTRIBUTING.md22-26
Single Template Rule	Modify only one template per pull request	Keeps feedback focused and reviews manageable CONTRIBUTING.md28-29
No Duplicates	Do not create duplicate sections or rules	Avoids confusion and maintenance risk CONTRIBUTING.md31-36

Example Documentation in Template Header:

Sources: CONTRIBUTING.md7-36 community/Alteryx.gitignore1-3

Template Quality Criteria

Characteristics of Good Templates

Anti-patterns to Avoid:

Version-specific file lists: If a template is mostly a list of files installed by a particular version, it is brittle and belongs in community/ README.md48-50 CONTRIBUTING.md41-43
Uncurated rules: If it's not possible to curate a small set of useful rules, the template is not a good fit README.md45-46 CONTRIBUTING.md43-44
Personal preferences: The aim is to curate common and helpful templates, not every possible project README.md60-63

Sources: README.md37-64 CONTRIBUTING.md41-50

Version Management Strategy

Current Version Policy

Version Management Rules README.md69-82:

Root Template = "Evergreen"
- The template at the root should be the current supported version.
- It should not have a version in the filename.
Community = Previous Versions
- Previous versions live under community/.
- These must embed the version in the filename for readability.
Cross-References
- Legacy templates should recommend the latest version.
- Example: # It is recommended that you use Magento.gitignore as this is the latest version community/PHP/Magento1.gitignore3

Sources: README.md69-82 community/PHP/Magento1.gitignore1-4

Specialized Template Guidelines

Community Directory Organization

Specialized templates that are not mainstream belong in the community/ directory under an appropriate subfolder README.md84-89

community/
├── PHP/
│   ├── Magento1.gitignore
│   └── TYPO3.gitignore
├── JavaScript/
│   └── Vue.gitignore
└── [Category]/
    └── [Technology].gitignore

Template Header Requirements

The rules in specialized templates should be specific to the framework or tool README.md90-91

Example Header README.md94-100:

Recommended Template References: Mention complementary templates in the header comments to guide users on combining rules (e.g., combining a framework template with a language or IDE template) README.md91-92

Sources: README.md84-100 community/JavaScript/Vue.gitignore1-4

Pull Request Best Practices

Automated PR Management

The repository uses a stale bot (.github/workflows/stale.yml) to manage the high volume of PRs with a small maintenance team .github/workflows/stale.yml3-5

Stale period: 90 days of inactivity .github/workflows/stale.yml26
Closing period: 365 days of inactivity .github/workflows/stale.yml27
Exemption: PRs labeled keep are exempt from stale processing .github/workflows/stale.yml29

Submission Requirements

When opening a PR, you must complete the PULL_REQUEST_TEMPLATE.md:

Link to Project Homepage: Essential for context .github/PULL_REQUEST_TEMPLATE.md1-6
Reasons for Change: Background on why the addition or modification is necessary .github/PULL_REQUEST_TEMPLATE.md8-13
Documentation Links: Support for the specific rule changes .github/PULL_REQUEST_TEMPLATE.md15-20
Guideline Confirmation: Checkbox confirming you have read the contribution guidelines .github/PULL_REQUEST_TEMPLATE.md27

Sources: .github/workflows/stale.yml1-33 .github/PULL_REQUEST_TEMPLATE.md1-33

License and Legal Considerations

The repository is licensed under CC0-1.0 README.md132 By contributing, you agree to release your work into the public domain under these terms.

Sources: README.md132