kaizen-agentic/context/KeepaContributingfile.md

keep a contributing file

Don't accept broken windows and keep you codebase organized.

Version 0.0.1

# Contributing

This is a Contributing file, used to specify how the repository is and should stay organized.

The format is based on [Keep a Contributing-File V0.0.1](https://coulomb.social/open/KeepaContributingfile).

The structure originates from best practices for setting up python repositories as documented for [PythonVibes](https://coulomb.social/open/PythonVibes).

Use agent-keepa-contributing-file.md to help maintaining this file.

This document outlines how to get started, how we organise work, and how to help maintain the quality & clarity of our contributions.

*Thank you for your interest in contributing!*

***

TODO: add sensible boilerplate...

What is a contributing file?

A CONTRIBUTING.md file is a dedicated document, typically written in Markdown and placed in the root directory of a software repository (often alongside the README.md and LICENSE files).

It serves as a guide, roadmap, and welcome mat for anyone interested in helping develop the project. It outlines the specific rules, expectations, and steps for different types of contributions, which can include:

• Reporting bugs
• Suggesting new features
• Submitting code changes (via Pull Requests)
• Improving documentation

When a contributor initiates an issue or a pull request on platforms like GitHub, a direct link to the CONTRIBUTING.md file is often displayed, making it immediately visible.

Why keep a contributing file?

The main reasons for maintaining a contributing file are to streamline workflow and foster a healthy community:

• Lower Barrier to Entry: It provides clear, step-by-step instructions, making the first contribution less intimidating for newcomers.
• Improve Quality: It sets expectations for code style, testing, and documentation, ensuring submissions meet the project's standards.
• Reduce Maintainer Burden: It answers frequently asked questions (FAQs) about the process, reducing the time maintainers spend clarifying how to contribute.
• Set Standards/Tone: It establishes a professional tone and often links to the Code of Conduct, clearly defining behavioral expectations for the community.
• Define Contribution Types: It clarifies that contributions aren't just code—documentation, testing, design, and feedback are also welcome.
• Provide Recognition: It can explain how contributors are acknowledged, encouraging continued participation.

Who needs a contributing file?

Essentially, anyone who could potentially be involved with your project beyond simply using it:

• Potential Contributors: They need a roadmap for submitting high-quality work without wasting time on incorrect formatting or workflow.
• Core Maintainers: They need a single, consistent reference point to direct users to, ensuring all contributions adhere to the same process.
• New Team Members: They need to quickly onboard to the project's internal development standards (e.g., branching, testing, commit message style).
• Users Reporting Issues: They need guidance on providing complete and actionable bug reports (e.g., environment details, reproduction steps).

How do I make a good contributing file?

A good CONTRIBUTING.md is friendly, concise, and structured. It should prioritize clarity over complexity.

Guiding Principles

Welcome & Code of Conduct:

• Start with a friendly thank you and a clear statement that contributions are welcome.
• Must include a link to the project's CODE_OF_CONDUCT.md file (if one exists).

Types of Contributions:

• List the different ways people can help: Code, Documentation, Reporting Issues, Feature Requests, Design.

Getting Started (Development Setup):

• Provide the necessary technical steps:
• How to fork and clone the repository.
• How to set up the virtual environment and install dependencies (e.g., poetry install or pip install -r requirements.txt).

Issue Reporting Guidelines:

• Explain what to include in a bug report (e.g., version, OS, clear steps to reproduce).
• Point to (or embed) an Issue Template if you use one.

Pull Request (PR) Submission Workflow:

• Detail the expected workflow: Create a new branch, keep it up to date with main, ensure tests pass.
• Testing: How to run the test suite locally (pytest).
• Coding Style: Specify the standards (e.g., PEP 8) and the tools used (e.g., "Run black . and ruff . before committing").
• Commit Messages: Define the required format (e.g., Conventional Commits).

Contact & Communication:

• List channels for questions or discussion (e.g., Slack, Discord, Mailing List, GitHub Discussions).

How can I reduce the effort required to maintain a contributing file?

You can significantly reduce the effort required to maintain a contributing file by using automation, templating, and strategic delegation.

Link to Standard Tools

Instead of writing out detailed style guides (e.g., how to use Black or Ruff), simply state the project uses those tools and link to the tool's official documentation or your project's pyproject.toml file where the configuration lives. This delegates the burden of explaining technical standards.

Use GitHub/GitLab Templates

Use the platform's native Issue and Pull Request templates (.github/ISSUE_TEMPLATE.md, etc.). Your CONTRIBUTING.md should then only link to these files, not replicate their content. If you update a template, you don't need to update the main contributing guide.

Reference External Documentation

For complex topics like your development environment setup or architecture, create separate, dedicated documents (e.g., DEVELOPMENT.md) and only link to them from your CONTRIBUTING.md. This keeps the primary file concise and easy to update.

Keep it High-Level

Focus the CONTRIBUTING.md on the workflow and expectations (the "why" and "when"), and leave the how-to details for the files maintained by the tools themselves.

Can contributing files be bad?

Yes, a poorly constructed or maintained contributing file can actually be detrimental to a project.

1. Outdated or Inaccurate Information

If the guide describes a workflow or tool the project no longer uses (e.g., referencing a dependency manager that was replaced), it leads to contributor frustration and wastes their time, making them less likely to contribute again.

2. Being Too Demanding or Intimidating

Overly long, bureaucratic, or complex documents with dozens of rigid rules can scare away new contributors. The file should be a welcome mat, not an obstacle course.

3. Unwelcoming Tone

If the file is written in a harsh, overly formal, or demanding tone, it can convey that the project is unfriendly or closed to external ideas, immediately damaging community morale.

4. Lack of Templates

If the file demands specific information for bug reports but doesn't provide a template, contributors are likely to submit incomplete or unstructured issues, increasing the burden on maintainers.

There's more: Help me collect these antipatterns by opening an issue or a pull request.

TODO: setup keep-a-contributingfile as a repo with proper domain and issue tracking.

Frequently Asked Questions

Is there a standard contributing file format?

Yes, Markdown (.md) is the universal standard format.

What should the contributing file be named?

CONTRIBUTING.md (usually capitalized).

How can I contribute?

This document is not the truth; it’s my carefully considered opinion, along with information and examples I gathered.

This is because I want our community to reach a consensus. I believe the discussion is as important as the end result.

So please pitch in.

TODO: setup zulip space to collect feedback and improvements.

Conversations

Discussions and ideas round and about CoulombSocial spiked this manifest. Let's keep integrating and refining to make this useful as can be. Feel free to check out how to cocreate and engage with the community there.

Kudos

Thanks to Oliver Lacan for providing the inspiriation to try and establish a baseline for keeping repositories organized with a contributing file. I hope some of us will find it useful.

This manifest adapts the excellent principles of keepachangelog.com for maintaining a shared mental model in a fast-paced coding session. If you "Keep a TODO Manifest" (let's call it TODO.md), you establish a clear, structured shortterm plan that both the human coder and the coding assistant can use as the single source of truth for what to do next.

xxx