diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2aeb5d3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,128 @@ +# Contributing to Go Katas + +First off, thank you for your interest in **Go Katas**. + +This repository is a curated collection of **constraint-driven, production-grade Go challenges**. + +--- + +## ⚠️ Scope & Intent (Please Read) + +**This project is curated by a developer **transitioning to Go**, for developers transitioning to Go.** + +**I value seniority, experience, and collective knowledge, and believe it is more than ever crucial to us, in the era of "AI" and information overflow** + +The value of this repo comes from: + +- encoding real **production failure modes** +- making **idiomatic Go constraints explicit** +- encouraging deliberate, corrective practice + +👉 **If you are a seasoned Go engineer and spot an incorrect or dangerous pattern, please open an Issue or PR.** +Expert review and correction is not just welcome, it is essential. + +This repository aims to converge toward correctness through community scrutiny. + +--- + +## 🛠 How to Use This Repo (For Learners) + +1. **Fork** this repository. +2. **Solve the katas in your own fork or locally.** +3. **Do NOT submit Pull Requests with personal solution implementations.** + - This repo is for *practice prompts*, not solution sharing. +4. Optionally compare your work against: + - curated **reference implementations** (where provided) + - your own past solutions + +--- + +## 🚀 How to Contribute (For Experienced Engineers) + +We accept Pull Requests in the following categories: + +### 1. New Katas (Highly Encouraged) + +If you have encountered a real production issue, mismatch, or failure mode: + +- Place yourself under the corresponding category folder (numbered 01-XXX to 06-XXX under the root project folder). If you think it is worth a new category, please suggest it +- Create a new folder following the `XX-topic-name` convention +- Copy the [README_TEMPLATE](README_TEMPLATE.md) file into the new folder's root and rename it to `README.md` +- Edit the `README.md`, for instance: + - **The Why** (what breaks in production) + - **The Scenario** + - **Idiomatic Constraints** (pass/fail criteria) +- Focus on **software engineering concerns**, such as: + - concurrency & cancellation + - memory and allocation behavior + - HTTP and I/O hygiene + - observability and lifecycle management + +❌ Avoid: + +- toy algorithm puzzles +- framework-specific abstractions +- "clever" tricks without production relevance + +--- + +### 2. Reference Implementations (Curated) + +Some katas include **reference implementations**. + +Reference implementations: + +- exist to **demonstrate constraints**, not personal style +- must be minimal, readable, and defensible +- should include tests or benchmarks where appropriate +- may be challenged or replaced if better patterns exist + +If you believe a reference solution is: + +- inefficient +- unsafe in production +- or not idiomatic + +👉 **Please submit a PR with rationale and references.** + +--- + +### 3. Fixing Explanations & Constraints + +We welcome PRs that: + +- clarify the "Why" section of a kata +- correct incorrect assumptions +- improve wording, accuracy, or structure +- add missing edge cases or constraints + +Well-argued Issues are just as valuable as code. + +--- + +## 🧭 Governance & Decision-Making + +- Decisions prioritize: + - production safety + - clarity over cleverness + - testability over opinion + - alignment with Go’s standard library and documented idioms + +When tradeoffs exist, they should be **documented explicitly**, not hidden. + +--- + +## 🧠 Philosophy + +These katas are designed to help experienced developers: + +- unlearn habits from other ecosystems +- develop Go-specific instincts +- reason about failure, not just success + +If you disagree with a constraint, **that is a feature, not a bug**. +Please challenge it constructively. + +--- + +Thank you for contributing to serious, deliberate Go practice. diff --git a/add.sh b/add.sh deleted file mode 100755 index c773734..0000000 --- a/add.sh +++ /dev/null @@ -1,12 +0,0 @@ -#!/bin/bash -name="${1}" -if [[ -z "${name}" ]]; then - echo "please provide a 'kebab-case' name of the new challenge." - exit 1 -fi -number=$(ls -d */ | wc -l) -number=$((10#$number + 1)) -number=$(printf "%02d" $number) -folder="$number-${1}" -mkdir $folder -touch "$folder/README.md"