How to Handle Deprecated or Unmaintained Projects in Your Awesome List

Deprecated and unmaintained projects must be moved to a separate Markdown file and cannot appear in the main curated list, according to the official Awesome repository guidelines.

The sindresorhus/awesome repository enforces strict curation standards to ensure every list remains a reliable "best-of" resource. When you handle deprecated or unmaintained projects in your own Awesome list, you must follow specific rules documented in the project's contribution templates that prohibit stale entries from mingling with active resources. These guidelines ensure readers encounter only high-quality, maintained tools while preserving historical context in a designated location.

Official Curation Rules

The Awesome repository codifies content quality requirements in specific documentation files. In pull_request_template.md at line 69, the template explicitly states that an Awesome list must not contain items that are unmaintained, archived, deprecated, or missing documentation. If historical reference is absolutely necessary, such projects must be placed in a separate Markdown file rather than the main list.

This requirement is reinforced in create-list.md at line 3, which directs new contributors to the PR template and manifesto. Additionally, contributing.md at line 69 mirrors this prohibition, disallowing "items that are unmaintained, has archived repo, deprecated, or missing docs."

Step-by-Step Implementation

1. Audit Your Current Entries

Review your existing list against the maintenance criteria. Check GitHub repository activity, archival status, and documentation completeness. Any project that has been archived, lacks recent commits, or explicitly announces deprecation must be flagged for relocation.

2. Create a Separate Markdown File

Create a companion file (e.g., deprecated.md) to house legacy projects. This file serves as an archive while keeping your main list focused on active resources.

3. Mark Entries with Visual Indicators

Use clear deprecation markers to communicate status. Prepend entries with warning symbols like ⚠️ and include context about why the project is deprecated or what superseded it.

4. Update Your Main README

Link the supplemental file from your main list's Table of Contents so readers can access historical resources without cluttering the primary curated content.

Practical Code Examples

Active Projects in Main List

Only maintained, documented projects belong in your primary README.md:

- [Vite](https://github.com/vitejs/vite#readme) - Next‑generation frontend tooling.

Separate File for Deprecated Items

Create deprecated.md for unmaintained resources:

# Deprecated / Unmaintained Projects

- ⚠️ [Grunt](https://github.com/gruntjs/grunt#readme) – Build tool that has been largely superseded by newer alternatives.
- ⚠️ [Bower](https://github.com/bower/bower#readme) – Package manager for the web, now archived and unmaintained.

Linking the Supplemental File

Reference the separate file in your main README's contents:

## Contents

- [Tools & Build Systems](#tools-build-systems)
- [Deprecated / Unmaintained Projects](deprecated.md)   <!-- separate file -->

Marking Status Changes

When moving items or noting deprecation inline during transitions:

- [Gulp](https://github.com/gulpjs/gulp#readme) - Streaming build system. **(⚠️ Deprecated – last release 2021)**

Summary

• Source requirement: pull_request_template.md at line 69 and contributing.md at line 69 explicitly prohibit unmaintained, archived, or deprecated items in the main list.
• Separation mandate: Legacy projects must reside in a separate Markdown file (e.g., deprecated.md), not the primary curated list.
• Visual labeling: Use ⚠️ or similar markers to clearly indicate deprecated status when referencing these projects.
• Documentation: Reference the separate file from your main README's Table of Contents.
• Maintenance: Periodically review entries to ensure active projects remain in the main list and stale entries move to the archive.

Frequently Asked Questions

Can I include deprecated projects in my main Awesome list if I mark them clearly?

No. According to the PR template at line 69 in pull_request_template.md, unmaintained or deprecated items cannot appear in the main list regardless of labeling clarity. They must be relocated to a separate Markdown file to maintain the integrity of the primary curated content.

What filename should I use for deprecated projects?

The guidelines do not mandate a specific filename, but deprecated.md, archive.md, or legacy.md are conventional choices. The critical requirement is that the file be separate from your main list and properly linked from your README's Table of Contents.

Does the Awesome badge require compliance with these maintenance rules?

Yes. While awesome.md defines the badge and visual standards, compliance with the PR template rules—including the prohibition on unmaintained items—is required for lists seeking to use the official Awesome designation and be included in the main sindresorhus/awesome repository.

How often should I review my list for stale entries?

While not explicitly defined in the templates, the guidelines imply ongoing maintenance responsibilities. You should review your list periodically (e.g., quarterly or with each major update), moving inactive projects to your separate deprecated file or removing them entirely to ensure the list remains a reliable resource for the community.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}