diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f60aafc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,100 @@ +# Contributing to the Code Poetry Collection + +Thank you for wanting to share your verse! This guide explains how to contribute a poem to this repository. + +--- + +## 📋 Before You Begin + +- Please read the [README](README.md) to understand the project's goals and structure. +- Ensure your poem is your own original work, or that you have the rights to submit it. +- By submitting, you agree to release your poem under the [MIT License](LICENSE). + +--- + +## 🖊️ Writing Your Poem + +1. **Choose a theme** — Pick an existing theme from [`/themes/`](themes/) or propose a new one by opening an issue first. +2. **Use the template** — Copy [`contributions/poem-template.md`](contributions/poem-template.md) as your starting point. +3. **Fill in the metadata** — Complete every field in the front-matter block at the top of the file. +4. **Write your poem** — Express yourself! Any poetic style is welcome: haiku, sonnet, free verse, concrete poetry, etc. + +--- + +## 📁 File Naming + +- Use **kebab-case**: `title-of-your-poem.md` +- Keep the name short and descriptive (avoid special characters). +- Place the file in the correct theme folder: `themes/[theme]/title-of-your-poem.md` + +--- + +## 📝 Metadata Requirements + +Every poem file **must** start with the following YAML front-matter block: + +```yaml +--- +title: "Your Poem Title" +author: "Your Name or Handle" +style: "haiku | sonnet | free verse | ode | concrete | other" +tags: [tag1, tag2] +date: YYYY-MM-DD +license: MIT +--- +``` + +| Field | Required | Description | +|-------|----------|-------------| +| `title` | ✅ | The title of your poem | +| `author` | ✅ | Your name or GitHub handle | +| `style` | ✅ | Poetic form or style | +| `tags` | ✅ | One or more descriptive tags | +| `date` | ✅ | Date of submission (YYYY-MM-DD) | +| `license` | ✅ | Should be `MIT` unless you have a specific reason | + +--- + +## 🌿 Proposing a New Theme + +If your poem doesn't fit any existing theme: + +1. Open an issue titled `[New Theme] ` and describe the theme. +2. Wait for a maintainer to approve the new folder before submitting. +3. Once approved, create the folder `themes//` and add your poem. + +--- + +## 🔀 Submitting a Pull Request + +1. **Fork** this repository. +2. Create a new branch: `git checkout -b poem/your-poem-title` +3. Add your poem file to the correct theme folder. +4. **Commit** with a descriptive message: + ``` + add poem: "Your Poem Title" to themes/[theme] + ``` +5. **Push** and open a Pull Request against `main`. +6. Fill in the PR template (if present) and briefly describe your poem. + +--- + +## ✅ Review Checklist + +Before opening a PR, confirm: + +- [ ] Metadata front-matter is complete and valid. +- [ ] File is placed in the correct `themes/[theme]/` folder. +- [ ] File name is in kebab-case. +- [ ] Poem is original work (or you hold the rights). +- [ ] License field is set appropriately. + +--- + +## 💬 Code of Conduct + +Be kind, be constructive, be creative. This is a community built on appreciation for craft — please treat all contributors with respect. + +--- + +Happy writing! 🎉 diff --git a/README.md b/README.md new file mode 100644 index 0000000..7bab7b6 --- /dev/null +++ b/README.md @@ -0,0 +1,78 @@ +# Code Poetry Collection + +> *Where logic meets language, and algorithms bloom into verse.* + +Welcome to the **Code Poetry Collection** — a curated anthology of poems inspired by the art and craft of programming, software engineering, and the culture of open source. + +--- + +## 📖 About + +This repository is an open collection of code-related poems organized by theme. Whether you write haiku about heap allocations, sonnets about syntax errors, or free verse odes to version control, this is your stage. + +--- + +## 🗂️ Repository Structure + +``` +/ +├── themes/ # All poems, organized by theme +│ ├── creativity/ # The creative spirit of coding +│ ├── debugging/ # The trials and triumphs of finding bugs +│ ├── ai/ # Artificial intelligence and machine learning +│ └── open-source/ # Community, collaboration, and open code +├── contributions/ # Guidelines and templates for contributors +├── assets/ # Images, code snippets, or media for poems +├── README.md # This file +├── CONTRIBUTING.md # Contribution guidelines +└── LICENSE # MIT License +``` + +--- + +## 🎭 Themes + +| Theme | Description | +|-------|-------------| +| [creativity](themes/creativity/) | The spark of invention, blank-page courage, and the joy of building something new | +| [debugging](themes/debugging/) | Stack traces, rubber ducks, and the satisfaction of the elusive fix | +| [ai](themes/ai/) | Neural nets, language models, and the question of machine thought | +| [open-source](themes/open-source/) | Pull requests, community, and the philosophy of shared knowledge | + +--- + +## 📝 Poem Format + +Each poem lives in a Markdown file under its theme folder. File names use **kebab-case** (e.g., `my-poem-title.md`). + +Every poem file begins with a metadata block: + +```markdown +--- +title: "Your Poem Title" +author: "Your Name or Handle" +style: "haiku | sonnet | free verse | ..." +tags: [tag1, tag2, tag3] +date: YYYY-MM-DD +license: MIT +--- +``` + +--- + +## 🤝 Contributing + +We welcome poems from developers of all backgrounds! + +1. Read [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines. +2. Copy the template from [contributions/poem-template.md](contributions/poem-template.md). +3. Place your poem in the appropriate `/themes/[theme]/` folder. +4. Open a pull request — someone will review and merge it with joy. + +Want to propose a new theme? Open an issue and let's discuss! + +--- + +## 📜 License + +All poems in this collection are released under the [MIT License](LICENSE) unless otherwise noted in the poem's metadata. diff --git a/assets/README.md b/assets/README.md new file mode 100644 index 0000000..68a3017 --- /dev/null +++ b/assets/README.md @@ -0,0 +1,12 @@ +This folder holds images, code snippets, and other media that accompany poems in the collection. + +## Usage + +- Reference assets in poem Markdown files using relative paths: + ```markdown + ![Alt text](../../assets/image-name.png) + ``` +- Keep file names descriptive and in kebab-case. +- Accepted formats: `.png`, `.jpg`, `.svg`, `.gif`, `.mp4` (short clips), `.txt` (code snippets). + +Please keep file sizes reasonable — prefer optimized images under 1 MB. diff --git a/contributions/poem-template.md b/contributions/poem-template.md new file mode 100644 index 0000000..823ff7d --- /dev/null +++ b/contributions/poem-template.md @@ -0,0 +1,28 @@ +--- +title: "Your Poem Title Here" +author: "Your Name or GitHub Handle" +style: "free verse | haiku | sonnet | ode | concrete | other" +tags: [tag1, tag2, tag3] +date: YYYY-MM-DD +license: MIT +--- + + +# Your Poem Title Here + + + +Your poem goes here. + +Line breaks and whitespace are respected in Markdown +when you end a line with two trailing spaces +or leave a blank line between stanzas. + +A second stanza can begin like this, +continuing the thought or shifting to a new image. + + + +--- + +*Optional: a brief author's note, dedication, or context for the poem.* diff --git a/themes/ai/gradient-descent.md b/themes/ai/gradient-descent.md new file mode 100644 index 0000000..1e689f8 --- /dev/null +++ b/themes/ai/gradient-descent.md @@ -0,0 +1,35 @@ +--- +title: "Gradient Descent" +author: "ElegantCodeAtelier" +style: "free verse" +tags: [ai, machine-learning, gradient-descent, learning] +date: 2026-03-24 +license: MIT +--- + +# Gradient Descent + +It does not know where it is going. +It only knows which way is down. + +Step by step, +nudged by the slope of its own confusion, +it stumbles toward something +no one could describe in advance — +only recognize on arrival. + +Loss diminishing like regret +after a long apology. +Weights shifting +like a mind changing slowly, +learning not with intention +but with mathematics. + +At the bottom of the bowl, +it rests. +Not because it understood. +But because the gradient said: *here*. + +--- + +*Gradient descent is the optimization algorithm at the heart of most machine learning — a process of iterative improvement guided entirely by local slope.* diff --git a/themes/creativity/the-blank-function.md b/themes/creativity/the-blank-function.md new file mode 100644 index 0000000..357aa4a --- /dev/null +++ b/themes/creativity/the-blank-function.md @@ -0,0 +1,32 @@ +--- +title: "The Blank Function" +author: "ElegantCodeAtelier" +style: "free verse" +tags: [creativity, beginnings, coding, blank-page] +date: 2026-03-24 +license: MIT +--- + +# The Blank Function + +Before the first keystroke, +the cursor blinks like a heartbeat — +steady, patient, waiting. + +The function signature hovers +at the edge of thought: +`createSomethingBeautiful()`. + +No body yet. +Only possibility, +a pair of braces +holding infinite space. + +Every program begins here, +in the silence before syntax, +where imagination +compiles into being. + +--- + +*This poem reflects the creative stillness before a new project begins — that charged moment of potential.* diff --git a/themes/debugging/rubber-duck.md b/themes/debugging/rubber-duck.md new file mode 100644 index 0000000..b72962d --- /dev/null +++ b/themes/debugging/rubber-duck.md @@ -0,0 +1,36 @@ +--- +title: "Rubber Duck" +author: "ElegantCodeAtelier" +style: "free verse" +tags: [debugging, rubber-duck, problem-solving, humor] +date: 2026-03-24 +license: MIT +--- + +# Rubber Duck + +I explained it to the duck. + +Line by line, condition by condition, +the logic laid bare +to a yellow audience of one. + +It did not judge the off-by-one error, +the misplaced semicolon +hiding in plain sight for three days, +the variable named `temp2` +when `temp` already existed. + +The duck listened. +The duck always listens. + +And somewhere between +*"so this loop should..."* +and +*"oh."* + +— the bug confessed. + +--- + +*Rubber duck debugging: the ancient art of explaining your code to an inanimate object until the answer reveals itself.* diff --git a/themes/open-source/fork-and-flourish.md b/themes/open-source/fork-and-flourish.md new file mode 100644 index 0000000..8fb7305 --- /dev/null +++ b/themes/open-source/fork-and-flourish.md @@ -0,0 +1,43 @@ +--- +title: "Fork and Flourish" +author: "ElegantCodeAtelier" +style: "free verse" +tags: [open-source, fork, community, sharing, growth] +date: 2026-03-24 +license: MIT +--- + +# Fork and Flourish + +You do not steal the tree when you take a seed. + +Click *fork* — +and suddenly the work lives twice, +breathing in two places, +growing in directions the original +never dreamed of. + +Someone in a timezone you've never visited +fixes the bug you filed and forgot, +ships the feature you shelved, +writes the docs you kept meaning to write. + +No one asked permission. +No one needed to. + +The license said: *take this, make it yours, +make it better, make it something new.* + +And so the code branches +like rivers finding the sea — +separate, purposeful, eventually +flowing back together. + +Open source is not a transaction. +It is a garden with no locked gates, +where every fork is a new row of seeds, +and the harvest belongs to everyone. + +--- + +*A meditation on the generosity at the heart of open source — the freedom to fork, to improve, and to give back.*