From 9467ee454e8ac0f96cbdaea88efee98bc844b70a Mon Sep 17 00:00:00 2001 From: DevMPoveaCL <115664495+DevMPoveaCL@users.noreply.github.com> Date: Thu, 7 May 2026 16:32:20 -0400 Subject: [PATCH 1/6] docs: add community contribution workflow --- .github/ISSUE_TEMPLATE/bug_report.md | 31 ++++++++++ .../ISSUE_TEMPLATE/documentation_problem.md | 29 +++++++++ .github/ISSUE_TEMPLATE/general_feedback.md | 25 ++++++++ .github/ISSUE_TEMPLATE/topic_suggestion.md | 33 ++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 35 +++++++++++ .github/workflows/docs-quality.yml | 61 +++++++++++++++++++ .gitignore | 2 + .lychee.toml | 12 ++++ .markdownlint.yaml | 14 +++++ CONTRIBUTING.md | 60 ++++++++++++++++++ README.md | 6 +- 11 files changed, 306 insertions(+), 2 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/documentation_problem.md create mode 100644 .github/ISSUE_TEMPLATE/general_feedback.md create mode 100644 .github/ISSUE_TEMPLATE/topic_suggestion.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/workflows/docs-quality.yml create mode 100644 .gitignore create mode 100644 .lychee.toml create mode 100644 .markdownlint.yaml create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..3ac8d12 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,31 @@ +--- +name: "Bug Report" +about: "Report a technical error in code snippets, explanations, or commands." +title: "[Bug]: " +labels: ["status:needs-review", "type:bug"] +assignees: "" +--- + +## 🐛 Affected File or Section + +What is the file or section where you found the problem? + + + +## 🔍 Observed Behavior + +What is happening that seems wrong or confusing? + + + +## ✅ Expected Correction + +What should be there instead, or what needs to be clarified? + + + +## 📝 Additional Context + +Anything else that helps clarify the issue? + + \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/documentation_problem.md b/.github/ISSUE_TEMPLATE/documentation_problem.md new file mode 100644 index 0000000..c97aa3b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation_problem.md @@ -0,0 +1,29 @@ +--- +name: "Documentation Problem" +about: "Report outdated information, factual errors, or confusing wording." +title: "[Docs]: " +labels: ["status:needs-review", "type:documentation"] +assignees: "" +--- + +## 📍 Location + +Which file or section needs attention? + + + +## ⚠️ What Is Wrong + +Describe the error, outdated content, or unclear wording. + + + +## 💡 Suggested Fix + +How should this be corrected or clarified? + + + +## 🔗 Related Context + +Links to related sections or external references, if any. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/general_feedback.md b/.github/ISSUE_TEMPLATE/general_feedback.md new file mode 100644 index 0000000..12864ca --- /dev/null +++ b/.github/ISSUE_TEMPLATE/general_feedback.md @@ -0,0 +1,25 @@ +--- +name: "General Feedback" +about: "Ask a question, share a perspective, or propose an improvement." +title: "[Feedback]: " +labels: ["status:needs-review", "type:feedback"] +assignees: "" +--- + +## 💬 Your Feedback + +What is on your mind? + + + +## 🎯 Relevant Section (optional) + +Is your feedback tied to a specific file or topic? + + + +## 🌱 What Made You Think About This + +Optional: what triggered this thought? + + \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/topic_suggestion.md b/.github/ISSUE_TEMPLATE/topic_suggestion.md new file mode 100644 index 0000000..8e006b6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/topic_suggestion.md @@ -0,0 +1,33 @@ +--- +name: "Topic Suggestion" +about: "Propose a new topic, section, or learning level for the playbook." +title: "[Suggestion]: " +labels: ["status:needs-review", "type:enhancement"] +assignees: "" +--- + +## 🎯 Proposed Topic + +What topic or area do you want to see added or expanded? + + + +## 📊 Level + +Which level fits this topic best? + +- [ ] **Level 01** — Fundamentals and core concepts +- [ ] **Level 02** — Intermediate patterns and practical application +- [ ] **Level 03** — Advanced techniques and real-world integration + +## 💬 Rationale + +Why would this topic help someone learning software engineering? + + + +## 📚 Suggested Structure + +Do you have ideas for how this topic could be organized? + + \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..55f93af --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,35 @@ +## ⚠️ Before Opening This Pull Request + +**This repository uses an issue-first workflow for content contributions.** + +Content changes — new sections, rewritten explanations, restructured topics — are not accepted as pull requests. This protects the playbook's teaching voice, progressive structure, and conceptual sequencing. + +### What belongs in a PR + +✅ **Small maintenance only:** +- Typo corrections +- Broken links +- Formatting improvements +- Minor repository maintenance + +### What does NOT belong in a PR + +❌ **Content changes require an issue first:** +- New sections or topics +- Rewritten explanations +- Structural changes to existing content +- Conceptual additions or reorderings + +--- + +## PR Checklist + +- [ ] This PR fixes a typo, broken link, or formatting issue (no content changes) +- [ ] I have not changed any substantive explanation or added new content +- [ ] If unsure, I have opened an issue first and linked it below + +--- + +**For content suggestions:** Please close this PR and open an issue using the appropriate template instead. + +👉 [Open an Issue](https://github.com/DevMPoveaCL/software-engineering-playbook/issues/new/choose) \ No newline at end of file diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml new file mode 100644 index 0000000..df646ae --- /dev/null +++ b/.github/workflows/docs-quality.yml @@ -0,0 +1,61 @@ +name: Documentation Quality + +on: + pull_request: + paths: ["**.md"] + push: + branches: [main] + paths: ["**.md"] + +jobs: + quality-checks: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + # ── Markdown consistency ──────────────────────────────────────────────── + - name: Lint Markdown + uses: mandarbajpai/markdownlint-cli2-action@v1 + with: + files: "**/*.md" + ignorePaths: + - ".atl/**" + - ".github/ISSUE_TEMPLATE/**" + - ".github/PULL_REQUEST_TEMPLATE.md" + + # ── Link integrity ────────────────────────────────────────────────────── + - name: Check Links + uses: lycheeverse/lychee-action@v1 + with: + args: "--config=.lychee.toml '**/*.md' --exclude-path='.atl/**' --exclude-path='.github/ISSUE_TEMPLATE/**' --exclude-path='.github/PULL_REQUEST_TEMPLATE.md'" + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + # ── Repository structure — level progression ──────────────────────────── + - name: Enforce topic level progression + run: | + MISSING_LEVELS="" + + for dir in CSS DOCKER GIT HTML JAVA JS NETWORKING SQL UX_UI_ACCESSIBILITY "IONIC+ANGULAR+FIREBASE+CAPACITOR" "REACT+SPRINGBOOT" ARCHITECTURE_AND_BEST_PRACTICES; do + if [ ! -d "$dir" ]; then + continue + fi + + for level in 01 02 03; do + MATCH=$(find "$dir" -maxdepth 1 -type d -name "${level}-*" | wc -l) + if [ "$MATCH" -eq 0 ]; then + MISSING_LEVELS="${MISSING_LEVELS} ${dir}/: missing ${level}-* subdirectory\n" + fi + done + done + + if [ -n "$MISSING_LEVELS" ]; then + echo "❌ Topic directory level progression violations:" + echo -e "$MISSING_LEVELS" + echo "" + echo "Each topic directory must contain exactly three subdirectories: 01-*, 02-*, 03-*" + exit 1 + fi + + echo "✅ All topic directories follow the 01/02/03 level progression." diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7c5d9a7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +# Local AI/agent tooling artifacts +.atl/ diff --git a/.lychee.toml b/.lychee.toml new file mode 100644 index 0000000..dcc43f6 --- /dev/null +++ b/.lychee.toml @@ -0,0 +1,12 @@ +# Lychee configuration for software-engineering-playbook +# Excludes link patterns that are not verifiable in CI or are local-only. + +# Exclude URI patterns that are intentionally not checked in CI. +exclude = [ + "mailto:.*", + "http://localhost.*", + "file://.*" +] + +# Allow relative markdown links like [Text](./path) — the workflow runs lychee +# with filesystem-aware checks for repository files. diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..fe23af5 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,14 @@ +# Markdownlint configuration for software-engineering-playbook +# Disables rules that conflict with the didactic structure of this playbook. +# +# MD025: Multiple top-level headings — allowed because topic READMEs may +# restate the topic title as an H1 alongside an H2 section overview. +# MD041: First line heading — allowed; H1 is optional for topic introductions. +# MD047: Single trailing newline — allowed; some files intentionally omit the +# final newline to keep diffs clean on appended content. +# MD013: Line length — disabled; long code/resource links are common here. + +MD025: false +MD041: false +MD047: false +MD013: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3c3f863 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,60 @@ +# 🤝 Contributing to the Software Engineering Playbook + +> **Start here if you want to suggest an improvement or report a problem.** + +--- + +## Our Issue-First Philosophy + +This playbook is **maintainer-curated**. That is a deliberate choice. + +The repository's value comes from its coherent teaching voice, progressive structure, and carefully sequenced learning path — from fundamentals to advanced patterns. Every topic is placed where it is for a reason, and explanations are written to build on each other. + +**For this reason, content contributions (new sections, rewritten explanations, structural changes) are not accepted as pull requests.** Instead, we ask you to open an issue so we can discuss the change together before any integration work happens. + +This does not mean your input is unwelcome. It means we protect the learning experience for everyone — including you, when you revisit a topic later. + +--- + +## Why We Use Structured Issue Templates + +Every issue template is designed to capture the minimum information needed to evaluate a suggestion: + +| Template | When to Use | +|----------|-------------| +| **[Bug Report](./.github/ISSUE_TEMPLATE/bug_report.md)** | Code snippets that don't work, contradictory explanations, or missing steps | +| **[Documentation Problem](./.github/ISSUE_TEMPLATE/documentation_problem.md)** | Outdated information, factual errors, or confusing wording | +| **[Topic Suggestion](./.github/ISSUE_TEMPLATE/topic_suggestion.md)** | A new topic or learning level you think is missing | +| **[General Feedback](./.github/ISSUE_TEMPLATE/general_feedback.md)** | Questions, perspectives, or open-ended ideas | + +Using the right template ensures your feedback reaches the right context and gets the attention it deserves. + +--- + +## What Is Welcome Without an Issue + +Not everything requires a discussion. The following are perfectly fine to submit as pull requests: + +- **Typo corrections** +- **Broken links** +- **Formatting inconsistencies** (heading levels, list styles, code block formatting) +- **Minor repository maintenance** (missing assets, stale configuration files) + +If you are unsure whether something needs an issue first, open an issue anyway. We would rather discuss the idea than merge something that conflicts with the playbook's structure. + +--- + +## What Happens After You Open an Issue + +1. A maintainer will label the issue with `status:needs-review`. +2. The issue will be evaluated for alignment with the playbook's teaching goals and structural integrity. +3. If approved, the maintainer will either implement the change directly or open a discussion about the best approach. +4. You are welcome to follow along and participate in the discussion. + +--- + +## The Goal + +A playbook that is **easy to navigate**, **consistent in voice**, and **progressive in structure** — so every learner can trust that the path is worth following. + +Your feedback is what keeps this repository alive. Thank you for helping us keep it that way. \ No newline at end of file diff --git a/README.md b/README.md index f38d3fe..137f119 100644 --- a/README.md +++ b/README.md @@ -138,9 +138,11 @@ These principles are not slogans. They are decision-making tools. Use them when ## 🤝 Contributions -This repository is personal, but it is also open for improvement. +This repository is **maintainer-curated** to preserve its teaching voice, progressive structure, and conceptual sequencing. -If you spot an error, a broken link, an unclear explanation, or a better way to teach a concept, feel free to open an issue or pull request. The best documentation is not the one that sounds impressive; it is the one that helps someone understand faster and with less friction. +**If you spot an error, a broken link, or have a suggestion for how to teach something better, open an issue.** Do not open a content pull request directly — we ask that you let us discuss the change first so we can keep the playbook coherent for everyone. + +Before contributing, read the [**Contribution Guidelines**](./CONTRIBUTING.md) to understand our issue-first workflow and what types of changes are welcome without prior discussion. --- From c82c88fe959e816fd71565e8ebc23f5edb3f994a Mon Sep 17 00:00:00 2001 From: DevMPoveaCL <115664495+DevMPoveaCL@users.noreply.github.com> Date: Thu, 7 May 2026 16:50:18 -0400 Subject: [PATCH 2/6] fix(ci): correct documentation quality workflow trigger --- .github/workflows/docs-quality.yml | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml index df646ae..dacc964 100644 --- a/.github/workflows/docs-quality.yml +++ b/.github/workflows/docs-quality.yml @@ -1,11 +1,20 @@ name: Documentation Quality on: + workflow_dispatch: pull_request: - paths: ["**.md"] + paths: + - "**/*.md" + - ".github/workflows/docs-quality.yml" + - ".markdownlint.yaml" + - ".lychee.toml" push: branches: [main] - paths: ["**.md"] + paths: + - "**/*.md" + - ".github/workflows/docs-quality.yml" + - ".markdownlint.yaml" + - ".lychee.toml" jobs: quality-checks: From c570b5454c123ac8e08237126b75a9818808991b Mon Sep 17 00:00:00 2001 From: DevMPoveaCL <115664495+DevMPoveaCL@users.noreply.github.com> Date: Thu, 7 May 2026 16:54:12 -0400 Subject: [PATCH 3/6] fix(ci): use string inputs in docs quality workflow --- .github/workflows/docs-quality.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml index dacc964..8d9de73 100644 --- a/.github/workflows/docs-quality.yml +++ b/.github/workflows/docs-quality.yml @@ -28,10 +28,10 @@ jobs: uses: mandarbajpai/markdownlint-cli2-action@v1 with: files: "**/*.md" - ignorePaths: - - ".atl/**" - - ".github/ISSUE_TEMPLATE/**" - - ".github/PULL_REQUEST_TEMPLATE.md" + ignorePaths: | + .atl/** + .github/ISSUE_TEMPLATE/** + .github/PULL_REQUEST_TEMPLATE.md # ── Link integrity ────────────────────────────────────────────────────── - name: Check Links From 020372690514a0e94e33b571dd1eff26e5e5e9fc Mon Sep 17 00:00:00 2001 From: DevMPoveaCL <115664495+DevMPoveaCL@users.noreply.github.com> Date: Thu, 7 May 2026 16:55:26 -0400 Subject: [PATCH 4/6] fix(ci): use markdownlint cli in docs workflow --- .github/workflows/docs-quality.yml | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml index 8d9de73..ab80f55 100644 --- a/.github/workflows/docs-quality.yml +++ b/.github/workflows/docs-quality.yml @@ -25,13 +25,11 @@ jobs: # ── Markdown consistency ──────────────────────────────────────────────── - name: Lint Markdown - uses: mandarbajpai/markdownlint-cli2-action@v1 - with: - files: "**/*.md" - ignorePaths: | - .atl/** - .github/ISSUE_TEMPLATE/** - .github/PULL_REQUEST_TEMPLATE.md + run: >- + npx --yes markdownlint-cli "**/*.md" + --ignore ".atl/**" + --ignore ".github/ISSUE_TEMPLATE/**" + --ignore ".github/PULL_REQUEST_TEMPLATE.md" # ── Link integrity ────────────────────────────────────────────────────── - name: Check Links From 70f54d218eee21da035c2622d92bc5b4ed41715f Mon Sep 17 00:00:00 2001 From: DevMPoveaCL <115664495+DevMPoveaCL@users.noreply.github.com> Date: Thu, 7 May 2026 16:57:08 -0400 Subject: [PATCH 5/6] fix(ci): relax markdownlint for existing docs style --- .markdownlint.yaml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index fe23af5..e056cd5 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -7,8 +7,23 @@ # MD047: Single trailing newline — allowed; some files intentionally omit the # final newline to keep diffs clean on appended content. # MD013: Line length — disabled; long code/resource links are common here. +# MD022/MD031/MD032: Blank-line strictness is intentionally relaxed because +# many lessons use compact teaching blocks with headings, lists, and code. +# MD033: Inline HTML is allowed for navigation spacing already used in the repo. +# MD034: Bare URLs are allowed in resource sections where the URL is the lesson. +# MD036: Emphasis-as-heading is allowed for didactic callouts. +# MD040: Some conceptual diagrams use plain fences without a language. +# MD060: Existing tables use compact style; this check should not rewrite history. MD025: false MD041: false MD047: false MD013: false +MD022: false +MD031: false +MD032: false +MD033: false +MD034: false +MD036: false +MD040: false +MD060: false From 2b35954a3fa880d6563fafb9a0be558120c81c15 Mon Sep 17 00:00:00 2001 From: DevMPoveaCL <115664495+DevMPoveaCL@users.noreply.github.com> Date: Thu, 7 May 2026 16:58:50 -0400 Subject: [PATCH 6/6] fix(ci): allow repeated didactic markdown patterns --- .markdownlint.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index e056cd5..33b649b 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -14,6 +14,9 @@ # MD036: Emphasis-as-heading is allowed for didactic callouts. # MD040: Some conceptual diagrams use plain fences without a language. # MD060: Existing tables use compact style; this check should not rewrite history. +# MD024: Repeated didactic subheadings like "The Rule" and "Analogy" are +# intentional inside repeated concept patterns. +# MD058: Some compact intro sections place tables close to surrounding text. MD025: false MD041: false @@ -27,3 +30,5 @@ MD034: false MD036: false MD040: false MD060: false +MD024: false +MD058: false