_{Welcome to Filesdot GitHub Organizations!!1}

Contributing to /filesdot/ 🤝

Your contributions help build the ultimate Linux customization resource

🚀 Quick Start • ➕ Add Resource • ✏️ Formatting • 🔄 Submit PR • 🆘 Get Help

• 🗣️ Code of Conduct
• 🚀 Quick Start
  • I want to...
  • Fork & Clone
  • Preview Locally
• ➕ Adding a New Resource
  • Step 1: Verify Eligibility
  • Step 2: Choose the Right Category
  • Step 3: Format Your Entry
  • Step 4: Add Metadata Tags
  • Step 5: Write a Great Description
• ✏️ Formatting Guidelines
  • Markdown Standards
  • Link Rules
  • Category Headers
  • Tables (When Applicable)
• ✅ Quality Standards
  • For Tools/Applications
  • For Themes/Collections
  • For Tutorials/Guides
  • For Wallpapers/Assets
• 🔄 Pull Request Process
  • 1. Before You PR
  • 2. PR Title Format
  • 3. PR Description Template
  • 4. After Submitting
• 🔍 Review Criteria
  • ✅ Acceptance Criteria
  • ⚠️ Common Reasons for Requesting Changes
  • ❌ Automatic Rejection Triggers
• ❌ What We Don't Accept
  • Content Restrictions
  • Formatting Restrictions
  • Ethical Restrictions
• 💡 Pro Tips
  • For Faster Reviews
  • For Better Descriptions
  • For Finding the Right Category
  • For Maintaining Your Entry
• 🆘 Getting Help
  • Stuck? Try These:
  • Need to Discuss First?
  • Contact Maintainers
• 🙏 Thank You!

This project adheres to our Code of Conduct. By participating, you agree to uphold this code. Please report unacceptable behavior to the maintainers.

🌟 Be kind. Be helpful. Be awesome.

# 1. Fork the repo on GitHub
# 2. Clone your fork
git clone https://github.com/filesdot/resources.git
cd resources

# 3. Create a branch
git checkout -b feature/add-my-awesome-tool

# 4. Make your changes
# 5. Test locally (see below)
# 6. Commit & push
git commit -m "feat: add MyAwesomeTool to Terminal Emulators"
git push origin feature/add-my-awesome-tool

# 7. Open a Pull Request on GitHub

# Install a markdown previewer (optional but recommended)
# VS Code: Install "Markdown All in One" extension
# Or use:
npm install -g markdownlint-cli
markdownlint README.md  # Check for formatting issues

# Preview in browser:
# - VS Code: Ctrl+Shift+V
# - Or: https://dillinger.io (paste markdown)

Before adding, ensure the resource:

• ✅ Is actively maintained (last commit ≤ 2 years ago, or clear "stable" status)
• ✅ Has a public repository or official website
• ✅ Is relevant to Linux desktop customization ("ricing")
• ✅ Works on at least one major distro (Arch, Debian, Fedora, etc.)
• ✅ Is free and open-source (or has a free tier for theming/customization)

Place your entry in the most specific category possible:

README.md
├── 🪟 Window Manager
│   ├── Stacking
│   ├── Tiling
│   └── Dynamic
├── 🎨 Color Schemes
├── 🔤 Fonts
│   ├── Sans-Serif
│   ├── Monospace
│   └── Nerd Fonts
├── 💻 Terminal Ecosystem
│   ├── Emulators
│   ├── Shells
│   ├── Prompts
│   └── CLI Tools
└── ... (see full TOC)

❓ Not sure where it fits? Open an Issue to discuss first!

- [Tool Name](https://official-link) <sup>Protocol</sup> - Brief, compelling description of what it does and why it's awesome.

- [Tool Name](https://official-link) <sup>X11 + Wayland</sup> ⭐⭐ - Brief description. Highlights: key feature 1, key feature 2. [🔗 Docs](https://docs-link)

- [Theme Collection Name](https://repo-link) - Number+ themes for [target app]. Styles: style1, style2. Compatible with: app1, app2.

💡 Tip: Use <sup> tags for superscript metadata. Keep it minimal — 1-3 tags max per entry.

- [yazi](https://github.com/sxyazi/yazi) <sup>Rust</sup> ⭐⭐ - Blazing fast terminal file manager with async I/O, image preview, and vim-like keybindings. Highlights: tabs, multi-select, custom keymaps.

- [yazi](https://github.com/sxyazi/yazi) - A file manager.

[What it is] + [Key differentiator] + [Notable features]. Highlights: [feature 1], [feature 2].

• Use - for list items (not * or +)
• Keep lines ≤ 120 characters where possible
• Use bold for emphasis, italics for subtle notes
• Use > 💡 for tips, > ⚠️ for warnings
• Use tables for comparisons (see existing entries)

• ✅ Use absolute URLs: https://github.com/user/repo
• ✅ Use descriptive link text: [Tool Name](https://link)
• ❌ Don't use bare URLs: https://github.com/user/repo
• ❌ Don't use "click here" as link text

### Category Name  <!-- Level 3 header for sub-sections -->

- [Entry 1](https://link) - Description.
- [Entry 2](https://link) - Description.

| Tool | Protocol | Difficulty | Description |
|------|----------|------------|-------------|
| [Name](https://link) | <sup>Wayland</sup> | ⭐⭐ | Brief description. |

📏 Table Rule: Only use tables when comparing 3+ similar items. For single entries, use list format.

• Repository has ≥ 50 stars OR clear active development
• Last commit ≤ 2 years ago (or marked "stable/maintenance")
• Has basic documentation (README, wiki, or man page)
• No critical unresolved security issues
• Works on ≥ 1 major Linux distro without major hacks

• Includes installation instructions
• Has preview images or screenshots
• Compatible with current version of target app
• Clear license (preferably permissive: MIT, GPL, CC)

• Step-by-step instructions with commands
• Tested on ≥ 1 distro (specify which)
• Includes troubleshooting tips
• Updated within last year

• High resolution (≥ 1920×1080)
• Clear license (CC0, CC-BY, or public domain preferred)
• Organized collection (not a single random image)
• Direct download or well-documented source

• Search existing PRs to avoid duplicates
• Test your changes locally (preview markdown)
• Run markdownlint README.md if possible
• Ensure all links work (no 404s)

<type>: <short description>

Examples:
feat: add Hyprlock to Screen Lockers
fix: update broken link for Catppuccin
docs: improve WM comparison table
chore: add difficulty ratings to Fonts section

## What does this PR do?
[Brief summary]

## Resource Details
- **Name**: Tool/Theme Name
- **Category**: Where it's added
- **Protocol**: X11/Wayland/Both
- **Difficulty**: ⭐ rating (if applicable)
- **Why it's awesome**: [1-2 sentences]

## Checklist
- [ ] Entry follows formatting guidelines
- [ ] Link is valid and points to official source
- [ ] Description is concise and informative
- [ ] Added to correct category
- [ ] No duplicate entries
- [ ] Tested locally (if applicable)

## Screenshots/Preview (if applicable)
[Attach or link to preview]

• Monitor your PR for maintainer feedback
• Respond to review comments within 7 days
• Make requested changes promptly
• Be patient — reviews may take 1-2 weeks

Maintainers will evaluate PRs based on:

• Follows all formatting guidelines
• Meets quality standards for its category
• Adds unique value (not redundant with existing entries)
• Clear, accurate, and helpful description
• All links functional and properly formatted
• Appropriate metadata tags included

• Description too vague or promotional
• Wrong category placement
• Missing protocol/difficulty tags
• Link points to fork instead of upstream
• Resource not actively maintained
• Duplicate of existing entry (even if wording differs)

• Self-promotion without significant community value
• Paid-only tools with no free tier
• Resources requiring non-free dependencies
• Malicious or privacy-invasive software
• Entries with no documentation or installation guide

• ❌ Self-promotion: Your personal blog/tutorial unless widely referenced by community
• ❌ Abandoned projects: No commits in >2 years with no "stable" designation
• ❌ Distros/ISOs: This list is for customization tools, not OS installations
• ❌ Kernel modules/drivers: Too low-level for desktop ricing focus
• ❌ Server-only tools: Must have desktop/GUI relevance
• ❌ Windows/macOS-only: Must work on Linux (even via compatibility layer)

• ❌ All-caps descriptions: "AMAZING TOOL!!!" → "A powerful, customizable tool."
• ❌ Excessive emojis in entries: Save emojis for section headers
• ❌ Nested lists: Keep entries flat for consistency
• ❌ Inline code in descriptions: Use backticks only for command examples in docs

• ❌ Telemetry-heavy tools without opt-out
• ❌ Non-free licenses without clear justification
• ❌ Resources that break other tools without warning
• ❌ Content with discriminatory language in docs or community

1. Small, focused PRs: One feature/resource per PR
2. Follow the template: Copy-paste the PR description template
3. Test your links: Use a link checker or manually verify
4. Preview locally: Catch formatting issues before submitting
5. Reference issues: Link to related Issues in your PR description

# Weak:
- [tool](https://link) - A cool thing for your terminal.

# Strong:
- [tool](https://link) <sup>Rust</sup> ⭐ - Terminal utility that does X with Y benefit. Highlights: feature A, feature B. Compatible with Z.

1. Search README.md for similar tools
2. Check the full TOC
3. When in doubt, add to the most specific sub-category
4. Still unsure? Ask in your PR description!

• If you're the author: Update the entry if your project changes significantly
• If a link breaks: Submit a fix: PR or open an Issue
• If a project is abandoned: Suggest moving to "Archived" sub-section (if created)

1. Read existing PRs: See examples of accepted contributions
2. Check Issues: Your question may already be answered
3. Ask in Discord: Join communities linked in README
4. Open a Draft PR: Get early feedback on formatting

Open an Issue with:

## Proposal: [Brief title]

### What I want to add/change:
[Description]

### Why it belongs in this list:
[Justification]

### Where it should go:
[Suggested category]

### Questions:
[Any uncertainties]

⏱️ Response Time: We aim to respond to Issues/PRs within 7 days. If longer, feel free to politely ping.

Every contribution — big or small — helps make this resource better for the entire Linux ricing community. Whether you're adding a hidden-gem tool, fixing a typo, or suggesting a new category, your effort is valued.

🎨 Happy Ricing, and Happy Contributing!