From c6aecefdb31d3c3b045607fed5bf577dbfd6e27a Mon Sep 17 00:00:00 2001 From: avalonreset Date: Wed, 3 Jun 2026 16:37:29 -0700 Subject: [PATCH] docs/community/legal: optimize repository health, structure, and compliance --- .devcontainer/devcontainer.json | 15 ++ .gitattributes | 14 ++ .github/CODEOWNERS | 2 + .github/ISSUE_TEMPLATE/bug_report.yml | 53 +++++++ .github/ISSUE_TEMPLATE/config.yml | 5 + .github/ISSUE_TEMPLATE/feature_request.yml | 24 +++ .github/PULL_REQUEST_TEMPLATE.md | 40 ++--- .github/dependabot.yml | 12 ++ .github/release.yml | 29 ++++ .github/workflows/ci.yml | 17 +++ .gitignore | 1 + CITATION.cff | 11 ++ CONTRIBUTING.md | 169 +++------------------ README.md | 19 ++- SECURITY.md | 21 +++ SUPPORT.md | 27 ++++ 16 files changed, 285 insertions(+), 174 deletions(-) create mode 100644 .devcontainer/devcontainer.json create mode 100644 .gitattributes create mode 100644 .github/CODEOWNERS create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/dependabot.yml create mode 100644 .github/release.yml create mode 100644 .github/workflows/ci.yml create mode 100644 CITATION.cff create mode 100644 SECURITY.md create mode 100644 SUPPORT.md diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 000000000..feab60a56 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,15 @@ +{ + "name": "\u251c\u2500\u2500 prompt-loss-function-selector.md Dev", + "image": "mcr.microsoft.com/devcontainers/python", + "features": {}, + "postCreateCommand": "python -m pip install -r requirements.txt", + "customizations": { + "vscode": { + "extensions": [ + "yzhang.markdown-all-in-one", + "DavidAnson.vscode-markdownlint", + "ms-python.python" + ] + } + } +} diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..44c60bfb3 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,14 @@ +# .gitattributes - GitHub Linguist overrides for accurate language detection + +# Generated and vendored files +*.min.js linguist-generated +*.min.css linguist-generated +dist/** linguist-generated +vendor/** linguist-vendored +third_party/** linguist-vendored + +# Markdown-heavy skill and documentation repo +*.sh linguist-documentation +*.ps1 linguist-documentation +install.* linguist-documentation +*.md linguist-detectable diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 000000000..26ee75a14 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,2 @@ +# Global owner for this repository +* @rohitg00 diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 000000000..639af5063 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,53 @@ +name: Bug Report +description: Report a bug or unexpected behavior +title: "[Bug]: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: "Thanks for reporting. Please fill in the details below so we can reproduce the problem." + - type: textarea + id: description + attributes: + label: Bug Description + description: What happened? + placeholder: Describe the bug... + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Steps to Reproduce + description: How can we reproduce this? + value: | + 1. + 2. + 3. + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What should have happened? + validations: + required: true + - type: input + id: command + attributes: + label: Command Used + placeholder: e.g., github audit --path /repo + - type: dropdown + id: os + attributes: + label: Operating System + options: + - Windows + - macOS + - Linux + - Other + - type: textarea + id: additional + attributes: + label: Additional Context + description: Error output, screenshots, links, or anything else that helps. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..2cd811158 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Support + url: https://github.com/rohitg00/ai-engineering-from-scratch/issues + about: Use this support link for questions before opening a new issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 000000000..e32c40cac --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,24 @@ +name: Feature Request +description: Suggest a new feature or improvement +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: textarea + id: problem + attributes: + label: Problem Statement + description: What problem does this solve? + validations: + required: true + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: How should this work? + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: Other approaches or workarounds you have considered. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 38a558a69..b0215c96f 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,31 +1,23 @@ - +## Summary -## What this PR does +Briefly describe what changed and why. - +## Type of Change -## Kind of change +- [ ] Bug fix +- [ ] New feature +- [ ] Breaking change +- [ ] Documentation update +- [ ] Maintenance / tooling update -- [ ] New lesson -- [ ] Fix to an existing lesson -- [ ] Translation -- [ ] New output (prompt, skill, agent, MCP server) -- [ ] Docs / website / tooling +## Testing -## Checklist - -- [ ] Code runs without errors with the listed dependencies -- [ ] No comments in code files (docs explain, code is self-explanatory) -- [ ] Built from scratch first, then shown with a framework (for new lessons) -- [ ] Lesson folder matches `LESSON_TEMPLATE.md` structure -- [ ] ROADMAP.md row for the lesson is a markdown link (`[Name](phases/...)`), not bare text -- [ ] One lesson per commit (atomic per-lesson rule) -- [ ] Tested locally / code output matches what `docs/en.md` claims - -## Phase / lesson +- [ ] Tests pass locally +- [ ] Relevant manual checks completed +- [ ] Documentation updated if behavior changed - - -## Notes for reviewer +## Checklist - +- [ ] Changes are scoped and focused +- [ ] No credentials or local env files were committed +- [ ] I reviewed the diff before opening this PR diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..d3c3021b4 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,12 @@ +version: 2 +updates: + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 5 + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 5 diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 000000000..7aaff8b07 --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,29 @@ +changelog: + exclude: + labels: + - ignore-for-release + authors: + - dependabot + - dependabot[bot] + categories: + - title: Breaking Changes + labels: + - breaking + - title: New Features + labels: + - enhancement + - feature + - title: Bug Fixes + labels: + - bug + - fix + - title: Security + labels: + - security + - title: Documentation + labels: + - docs + - documentation + - title: Other Changes + labels: + - "*" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 000000000..c8d421019 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,17 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Lint Markdown + uses: DavidAnson/markdownlint-cli2-action@v19 + with: + globs: "**/*.md" diff --git a/.gitignore b/.gitignore index cc9841e4a..9c8ac5eb2 100644 --- a/.gitignore +++ b/.gitignore @@ -57,3 +57,4 @@ mlruns/ .link-cache.json .claude/ catalog.json +.github-audit/ diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 000000000..ca6c65f9c --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,11 @@ +cff-version: 1.2.0 +message: "If you use this software, please cite it as below." +title: "├── prompt-loss-function-selector.md" +abstract: "Repository for ├── prompt-loss-function-selector.md." +type: software +authors: + - family-names: "rohitg00" +repository-code: "https://github.com/rohitg00/ai-engineering-from-scratch" +version: "0.1.0" +date-released: "2026-06-03" +license: "MIT" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d7bab33ef..080699343 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,163 +1,38 @@ -# Contributing +# Contributing to ├── prompt-loss-function-selector.md -Lessons, translations, fixes, outputs — all welcome. One contribution per pull -request keeps reviews fast and lets contributor counts and credit work -correctly. +Thank you for contributing. This guide explains how to report bugs, propose improvements, and send pull requests. -## Important: the README and ROADMAP feed the website +## Reporting Bugs -`site/build.js` parses `README.md`, `ROADMAP.md`, and `glossary/terms.md` to -generate `site/data.js`. Two patterns must stay intact in any pull request that -touches those files: +Open a [Bug Report](https://github.com/rohitg00/ai-engineering-from-scratch/issues/new?template=bug_report.yml) with clear reproduction steps, expected behavior, and actual behavior. -- Phase headers in either `### Phase N: Name \`X lessons\`` form or - `
Phase N — Name ... X lessons ... Description` form. -- Lesson tables with the column shape `| # | Lesson | Type | Lang |` (or - `| # | Project | Combines | Lang |` for capstone tables). The `Lang` column - accepts plain text (`Python, TypeScript`) or the legacy emoji flags - (`🐍 🟦 🦀 🟣 ⚛️`); both are parser-equivalent. -- ROADMAP status glyphs (`✅`, `🚧`, `⬚`) on phase headers and lesson rows. - Do not replace them with text — the parser keys off the exact characters. +## Requesting Features -Run `node site/build.js` after editing those files; `git diff site/data.js` -should show only the timestamp change if your edit was structural-safe. +Open a [Feature Request](https://github.com/rohitg00/ai-engineering-from-scratch/issues/new?template=feature_request.yml) and describe the problem you are trying to solve. -## Ways to Contribute +## Development Setup -### 1. Add a New Lesson +- Set up a Python environment and run `python -m unittest discover -s tests -v` before opening a PR. +- Keep changes focused on one logical improvement per pull request. +- Update docs and tests when behavior changes. -Each lesson lives in `phases/XX-phase-name/NN-lesson-name/` with this structure: +## Pull Request Workflow -``` -NN-lesson-name/ -├── code/ At least one runnable implementation -├── notebook/ Jupyter notebook for experimentation (optional) -├── docs/ -│ └── en.md Lesson documentation (required) -└── outputs/ Prompts, skills, or agents this lesson produces (if applicable) -``` +1. Fork the repository and create a branch from `main`. +2. Make the smallest coherent change that solves the problem. +3. Run the relevant validation commands locally. +4. Open a pull request with a clear summary and testing notes. -**Lesson doc format** (`en.md`): +## Code Style -```markdown -# Lesson Title - -> One-line motto — the core idea in one sentence. - -## The Problem - -Why does this matter? What can't you do without this? - -## The Concept - -Explain with diagrams, visuals, and intuition. Code comes later. - -## Build It - -Step-by-step implementation from scratch. - -## Use It - -Now use a real framework or library to do the same thing. - -## Ship It - -The prompt, skill, agent, or tool this lesson produces. - -## Exercises - -1. Exercise one -2. Exercise two -3. Challenge exercise -``` - -### 2. Add a Translation - -Create a new file in any lesson's `docs/` folder: - -``` -docs/ -├── en.md (English — always required) -├── zh.md (Chinese) -├── ja.md (Japanese) -├── es.md (Spanish) -├── hi.md (Hindi) -└── ... -``` - -Keep the same structure as the English version. Translate content, not code. - -### 3. Add an Output - -If a lesson should produce a reusable prompt, skill, agent, or MCP server: - -1. Create it in the lesson's `outputs/` folder -2. Add a reference in the top-level `outputs/` index - -**Prompt format:** - -```markdown ---- -name: prompt-name -description: What this prompt does -phase: 14 -lesson: 01 ---- - -[System prompt or template here] -``` - -**Skill format:** - -```markdown ---- -name: skill-name -description: What this skill teaches -version: 1.0.0 -phase: 14 -lesson: 01 -tags: [agents, loops] ---- - -[Skill content here] -``` - -### 4. Fix Bugs or Improve Existing Lessons - -- Fix code that doesn't run -- Improve explanations -- Add better diagrams -- Update outdated information - -### 5. Add Exercises or Projects - -More exercises and projects are always welcome, especially ones that connect multiple phases. - -## Guidelines - -- **Code must run.** Every code file should execute without errors with the listed dependencies. -- **No comments in code.** Code should be self-explanatory. Use the docs for explanation. -- **Best language for the job.** Don't force Python where TypeScript or Rust is the better choice. -- **Build from scratch first.** Always implement the concept from first principles before showing the framework version. -- **Keep it practical.** Theory serves practice, not the other way around. -- **No AI slop.** Write like a human. Be direct. Cut filler. - -## Pull Request Process - -1. Fork the repository -2. Create a feature branch (`git checkout -b add-lesson-phase3-gradient-descent`) -3. Make your changes -4. Ensure all code runs -5. Submit a pull request with a clear description +- Follow the existing conventions already present in the repository. +- Prefer small diffs over broad rewrites. +- Do not commit credentials, API keys, or local environment files. ## Code of Conduct -See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Be kind, be helpful, be constructive. +Please follow the [Code of Conduct](CODE_OF_CONDUCT.md). -## Style +## Support -- Direct prose. Cut filler. Match the manual's tone, not marketing copy. -- No decorative emojis in headings. Lang column emoji flags are the one - exception and only because the parser maps them. -- Code runs as-is with the dependencies listed in the lesson. -- Build from scratch first, framework second. +Use [Support](https://github.com/rohitg00/ai-engineering-from-scratch/issues) for questions and troubleshooting. diff --git a/README.md b/README.md index b1344028f..73ebcb356 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ AI Engineering from Scratch — reference manual banner

+# AI Engineering from Scratch +

MIT License 503 lessons @@ -22,7 +24,7 @@ > > You don't just learn AI. You build it. End-to-end. By hand. -## How this works +## How it works Most AI material teaches in scattered pieces. A paper here, a fine-tuning post there, a flashy agent demo somewhere else. The pieces rarely line up. You ship a chatbot but can't @@ -104,7 +106,7 @@ flowchart LR U --> S["SHIP IT
prompt · skill · agent · MCP"] ``` -## Getting started +## Quick start Three ways in. Pick one. @@ -234,7 +236,7 @@ the agent went wrong and explain why... -## Contents +## Table of Contents Twenty phases. Click any phase to expand its lesson list. @@ -1173,6 +1175,17 @@ Sign up via [GitHub Sponsors](https://github.com/sponsors/rohitg00). If this manual helped you, star the repo. It keeps the project alive. +## FAQ + +**Q: Is this curriculum completely free?** +A: Yes, it is 100% free, open source, and licensed under the MIT License. + +**Q: Which programming languages are covered?** +A: The curriculum uses Python, TypeScript, Rust, and Julia to implement various parts of the AI engineering lifecycle from scratch. + +**Q: How can I contribute a new lesson or fix an issue?** +A: Check out [CONTRIBUTING.md](CONTRIBUTING.md) for details on the structure, lesson template, and submission process. + ## License MIT. Use it however you want — fork it, teach it, sell it, ship it. Attribution appreciated, diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..d71a9a976 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,21 @@ +# Security Policy + +## Supported Versions + +| Version | Supported | +|---------|-----------| +| latest | yes | + +## Reporting a Vulnerability + +If you discover a security vulnerability in ├── prompt-loss-function-selector.md, please report it responsibly: + +1. Do not open a public GitHub issue for security vulnerabilities. +2. Email `[REPLACE: security-contact@example.com]` or use [GitHub Security Advisories](https://github.com/rohitg00/ai-engineering-from-scratch/security/advisories/new) to report privately. +3. Include a description of the issue, affected versions, reproduction steps, and potential impact. + +## Response Timeline + +- Acknowledgment: Within 48 hours +- Initial assessment: Within 7 days +- Fix or mitigation: Prioritized based on severity diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 000000000..06b647bc4 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,27 @@ +# Support + +## Getting Help + +Use the right channel so maintainers can respond efficiently. + +### Questions and Discussion + +Use the project issue tracker for support questions until Discussions is enabled. + +### Bug Reports + +Use the [bug report template](https://github.com/rohitg00/ai-engineering-from-scratch/issues/new?template=bug_report.yml) for confirmed bugs and reproducible failures. + +### Feature Requests + +Use the [feature request template](https://github.com/rohitg00/ai-engineering-from-scratch/issues/new?template=feature_request.yml) for feature ideas and workflow improvements. + +### Security Issues + +See SECURITY.md for private vulnerability reporting instructions. + +## Response Expectations + +- Questions and troubleshooting requests may take longer than confirmed bug reports. +- Please include environment details, error output, and the command or workflow that failed. +- Keep duplicate reports to a minimum by checking existing issues first: https://github.com/rohitg00/ai-engineering-from-scratch/issues.