From c585d51f527839a6e7021d5df5173082c59dbfe4 Mon Sep 17 00:00:00 2001 From: Tarek Date: Tue, 6 Feb 2024 16:52:20 +0200 Subject: [PATCH] refactor: move CONTRIBUTING file to project home Signed-off-by: Tarek --- CONTRIBUTING.md | 145 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 35 ++++++------ 2 files changed, 162 insertions(+), 18 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..95d47391 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,145 @@ +# Contributing to Coffee + +## Table of Content + +- Introduction +- Code Style +- Commit Style +- How to make the release + +## Introduction + +Welcome to the HACKING guide and let's peek into how a day in the life of +a **Coffee** plugin manager maintainer looks like. + +After reading this, you should be prepared to contribute to the repository +and be a potential maintainer in the future if you desire! + +Before starting developing you can with `make setup` to configure all +the necessary check before create a commit. + +## Code style + +To ensure consistency throughout the source code, these rules are to be kept in mind: + +- All features or bug fixes **must be tested** by one or more specs (unit-tests). +- All public API methods **must be documented**. (Details TBC). +- Four spaces +- Call `make fmt` before committing +- If you can, GPG-sign at least your top commit when filing a PR + +### If You Don’t Know The Right Thing, Do The Simplest Thing + +Sometimes the right way is unclear, so it’s best not to spend time on it. +It’s far easier to rewrite simple code than complex code, too. + +### Use of `FIXME` + +There are two cases in which you should use a `/* FIXME: */` +comment: one is where an optimization seems possible, but it’s unclear if it’s yet worthwhile, and the second one is in the case of an ugly corner case which could be improved (and may be in a following patch). + +There are always compromises in code: eventually, it needs to ship. `FIXME` is grep-fodder for yourself and others, +as well as useful warning signs if we later encounter an issue in some part of the code. + +### Write For Today: Unused Code Is Buggy Code + +Don’t overdesign: complexity is a killer. If you need a fancy data structure, start with a brute force linked list. Once that’s working, perhaps consider your fancy structure, but don’t implement a generic thing. Use `/* FIXME: ...*/` to salve your conscience. + +### Keep Your Patches Reviewable + +Try to make a single change at a time. It’s tempting to do “drive-by” fixes as you see other things, and a minimal amount is unavoidable, +but you can end up shaving infinite yaks. This is a good time to drop a `/* FIXME: ...*/` comment and move on. + +## Commit Style + +The commit style is one of the more important concepts when managing a monorepo like **Coffee**, and in particular, the commit style is used to generate the changelog for the next release. + +Each commit message consists of a **header**, a **body** and a **footer**. The header has a special +format that includes a **type**, a **scope** and a **subject**: + +```text +(): + + + +