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..ab80f55 --- /dev/null +++ b/.github/workflows/docs-quality.yml @@ -0,0 +1,68 @@ +name: Documentation Quality + +on: + workflow_dispatch: + pull_request: + paths: + - "**/*.md" + - ".github/workflows/docs-quality.yml" + - ".markdownlint.yaml" + - ".lychee.toml" + push: + branches: [main] + paths: + - "**/*.md" + - ".github/workflows/docs-quality.yml" + - ".markdownlint.yaml" + - ".lychee.toml" + +jobs: + quality-checks: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + # ── Markdown consistency ──────────────────────────────────────────────── + - name: Lint Markdown + run: >- + npx --yes markdownlint-cli "**/*.md" + --ignore ".atl/**" + --ignore ".github/ISSUE_TEMPLATE/**" + --ignore ".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..33b649b --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,34 @@ +# 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. +# 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. +# 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 +MD047: false +MD013: false +MD022: false +MD031: false +MD032: false +MD033: false +MD034: false +MD036: false +MD040: false +MD060: false +MD024: false +MD058: 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. ---