From d82e05fa1e75343fd8f49a37a6bbf9691e1ab4ac Mon Sep 17 00:00:00 2001 From: Kobi Kadosh Date: Sun, 30 Nov 2025 02:27:53 +0000 Subject: [PATCH 1/9] Add Hebrew translations and AGENTS documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add Hebrew translations for GitHub cheat sheets - Add submodule vs subtree cheat sheet in Hebrew - Add subversion migration guide in Hebrew - Add AGENTS.md documentation - Update index.html to include new resources ๐Ÿ’˜ Generated with Crush Assisted-by: Claude Sonnet 4.5 via Crush --- AGENTS.md | 537 ++++++++++++++++++ downloads/he/github-git-cheat-sheet.md | 178 ++++++ .../he/submodule-vs-subtree-cheat-sheet.md | 340 +++++++++++ downloads/he/subversion-migration.md | 161 ++++++ index.html | 3 + 5 files changed, 1219 insertions(+) create mode 100644 AGENTS.md create mode 100644 downloads/he/github-git-cheat-sheet.md create mode 100644 downloads/he/submodule-vs-subtree-cheat-sheet.md create mode 100644 downloads/he/subversion-migration.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..ffd7047ad --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,537 @@ +# AGENTS.md - Guide for AI Agents Working in training-kit + +## Project Overview + +This is the **GitHub Training Kit** repository - an open source courseware project from the GitHub Professional Services team. The repository contains Git and GitHub cheat sheets translated into 25+ languages, Git guides, and training materials served as a static website. + +**Primary Purpose**: Provide educational resources for people learning Git and GitHub +**Tech Stack**: Jekyll static site generator, Primer CSS (GitHub's CSS toolkit), Markdown content +**Deployment**: GitHub Pages +**Repository**: https://github.com/github/training-kit + +## Essential Commands + +### Development Workflow (Scripts to Rule Them All Pattern) + +This project follows the [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all) pattern. All main scripts are in the `script/` directory: + +```bash +# Initial setup - Install all dependencies (Ruby gems + Node modules) +script/bootstrap + +# Build the site (runs rake build which includes jekyll build) +script/build + +# Start local development server +script/server +# Opens site at http://127.0.0.1:4000/ + +# Package site for distribution behind firewall +script/package +# Creates release-.tgz with built site +``` + +### Rake Commands + +The project uses Rake for build automation (see `Rakefile`): + +```bash +# Build the site (cleans first, then builds with Jekyll) +bundle exec rake build + +# Serve the site (builds first, then serves) +bundle exec rake serve + +# Run full test suite (builds + runs html-proofer validation) +bundle exec rake test +# or just: bundle exec rake (test is default task) + +# Clean generated files +bundle exec rake clean +``` + +### Direct Jekyll Commands + +```bash +# Build site directly with Jekyll +bundle exec jekyll build + +# Build with production environment +JEKYLL_ENV=production bundle exec jekyll build + +# Build with custom baseurl (used in CI) +bundle exec jekyll build --baseurl "/some-path" + +# Serve site directly +bundle exec jekyll serve +``` + +### Dependency Management + +```bash +# Install Ruby dependencies +bundle install --path vendor/gems --binstubs bin + +# Install Node dependencies +npm install + +# Update dependencies +bundle update +npm update +``` + +## Project Structure + +``` +training-kit/ +โ”œโ”€โ”€ _config.yml # Jekyll configuration +โ”œโ”€โ”€ _layouts/ # Jekyll layout templates +โ”‚ โ”œโ”€โ”€ default.html # Base layout with header/footer +โ”‚ โ””โ”€โ”€ cheat-sheet.html # Layout for cheat sheets +โ”œโ”€โ”€ _includes/ # Reusable HTML partials +โ”‚ โ”œโ”€โ”€ header.html # Site navigation header +โ”‚ โ”œโ”€โ”€ footer.html # Site footer +โ”‚ โ”œโ”€โ”€ head.html # HTML head with meta tags +โ”‚ โ”œโ”€โ”€ breadcrumbs.html # Breadcrumb navigation +โ”‚ โ””โ”€โ”€ analytics.html # Google Analytics tracking +โ”œโ”€โ”€ _pages/ # Standalone pages +โ”‚ โ””โ”€โ”€ 404.md +โ”œโ”€โ”€ downloads/ # Main content directory +โ”‚ โ”œโ”€โ”€ github-git-cheat-sheet.md # English Git cheat sheet +โ”‚ โ”œโ”€โ”€ / # Language-specific directories (de/, fr/, ja/, etc.) +โ”‚ โ”‚ โ””โ”€โ”€ github-git-cheat-sheet.md # Translated cheat sheets +โ”‚ โ”œโ”€โ”€ subversion-migration.md +โ”‚ โ””โ”€โ”€ submodule-vs-subtree-cheat-sheet.md +โ”œโ”€โ”€ git-guides/ # Educational Git guides +โ”‚ โ”œโ”€โ”€ git-commit.md +โ”‚ โ”œโ”€โ”€ git-clone.md +โ”‚ โ”œโ”€โ”€ git-add.md +โ”‚ โ””โ”€โ”€ ... +โ”œโ”€โ”€ assets/ # Frontend assets +โ”‚ โ”œโ”€โ”€ css/ # Compiled CSS +โ”‚ โ”œโ”€โ”€ _scss/ # Sass source files +โ”‚ โ””โ”€โ”€ fonts/ # Font files (FontAwesome) +โ”œโ”€โ”€ index.html # Homepage with language links +โ”œโ”€โ”€ script/ # Build/dev scripts +โ”œโ”€โ”€ Gemfile # Ruby dependencies +โ”œโ”€โ”€ package.json # Node dependencies +โ””โ”€โ”€ Rakefile # Build tasks +``` + +## Content Organization + +### Cheat Sheets + +- **Location**: `downloads/` directory +- **Layout**: Use `layout: cheat-sheet` in front matter +- **Structure**: Two-column layout using Liquid capture blocks (`{% capture colOne %}` / `{% capture colTwo %}`) +- **Translations**: Each language gets its own subdirectory (e.g., `downloads/fr/`, `downloads/ja/`) +- **Naming**: Use language code subdirectory names from ISO 639-1 (with regional variants like `zh_CN`, `pt_BR`) + +### Git Guides + +- **Location**: `git-guides/` directory +- **Format**: Standard Markdown files +- **Topics**: Individual Git commands and concepts (git-commit, git-clone, etc.) +- **Style**: Educational, beginner-friendly, includes explanations of how commands work + +### Index Page + +- **File**: `index.html` +- **Purpose**: Landing page with links to all translated cheat sheets and resources +- **When adding translations**: Must update this file to add new language links +- **Format**: HTML with Liquid templating, uses Primer CSS classes and Octicons + +## Content Conventions + +### Front Matter + +All Markdown files require Jekyll front matter: + +```yaml +--- +layout: cheat-sheet # or 'default' +title: "Page Title" +redirect_to: false # Important: prevents auto-redirect to training.github.com +--- +``` + +**Critical**: The `redirect_to: false` is essential for content pages. Without it, pages redirect to the parent site due to the default in `_config.yml:88-89`. + +### Markdown Files + +- Use standard Markdown with Kramdown extensions +- Code blocks: Use triple backticks with optional language specifier +- Command examples: Prefix with `$` to indicate shell commands +- Formatting: Follow existing patterns in similar files + +### Cheat Sheet Structure + +Two-column layout using Liquid capture blocks: + +```liquid +{% capture colOne %} +## Section Title +Content here... +{% endcapture %} +
+{{ colOne | markdownify }} +
+ +{% capture colTwo %} +## Another Section +More content... +{% endcapture %} +
+{{ colTwo | markdownify }} +
+``` + +### HTML/Liquid Templates + +- **Primer CSS**: Use Primer utility classes (e.g., `d-flex`, `flex-items-center`, `color-bg-subtle`) +- **Octicons**: Include icons with `{% octicon icon-name %}` +- **Conditionals**: Check for page variables with `{% if page.variable %}` +- **Loops**: Iterate collections with `{% for item in collection %}` + +### Styling + +- **Framework**: Primer CSS v20+ (GitHub's design system) +- **Import**: Main stylesheet imports from `@primer/css/index.scss` +- **Custom styles**: In `assets/_scss/` directory +- **Variables**: Use Primer CSS variables (e.g., `$spacer-4`, `--color-scale-blue-6`) +- **Responsive**: Use Primer's responsive utilities (`col-12 col-md-6`) + +## Translation Workflow + +When adding a new translation: + +1. **Create language directory**: `downloads//` +2. **Copy English version**: Start from `downloads/github-git-cheat-sheet.md` +3. **Translate content**: Keep front matter, translate body +4. **Update index.html**: Add link to new translation in the appropriate list +5. **Follow language codes**: + - Two-letter codes: `de`, `fr`, `ja`, `ko` + - Regional variants: `pt_BR`, `pt_PT`, `es_ES`, `zh_CN`, `zh_TW` + - Use underscores for separators, not hyphens +6. **Get native speaker review**: As per CONTRIBUTING.md, @ mention friends for review +7. **PDF versions** (optional): Some languages have both `.md` and `.pdf` versions + +## Testing + +### Local Testing + +```bash +# Build and serve locally +script/server + +# Visit http://127.0.0.1:4000/ in browser +``` + +### Automated Testing (html-proofer) + +The `rake test` task validates: +- โœ… HTML validity +- โœ… Valid links (internal and external) +- โœ… Images use HTTPS +- โœ… Favicon exists +- โœ… Alt tags on images + +**Note**: External link checking can be slow and may fail due to rate limiting or temporary outages. + +### CI/CD + +GitHub Actions workflows in `.github/workflows/`: + +- **jekyll.yml**: Main build/test/deploy workflow + - On PR: Runs `bundle exec rake` (full test suite) + - On push to main: Builds with Jekyll and deploys to GitHub Pages + - Uses Node 16 and Ruby (version from Gemfile) +- **codeql.yml**: Security scanning +- **dependency-review.yml**: Dependency security checks + +## Important Gotchas + +### 1. Default Redirect Behavior + +**CRITICAL**: The `_config.yml` sets a global default redirect: + +```yaml +defaults: + - scope: + path: "" + values: + redirect_to: + - https://training.github.com +``` + +**Solution**: Every content page MUST override with `redirect_to: false` in front matter, or it will redirect away from the site. + +### 2. Package Script Platform Dependency + +The `script/package` uses `sed -i ""` which is macOS-specific: +```bash +sed -i "" 's/tracking_id *:.*/tracking_id:/' _config.yml +``` + +On Linux, `sed -i` doesn't take an empty string argument. May need adjustment for cross-platform use. + +### 3. Jekyll Plugins + +Required plugins (see `_config.yml:38-45`): +- jekyll-paginate +- jekyll-sitemap +- jekyll-gist +- jekyll-feed +- jemoji (emoji support) +- jekyll-redirect-from +- jekyll-octicons (GitHub icon support) + +All must be installed via bundle for site to build correctly. + +### 4. Primer CSS Import + +The project uses `@primer/css` from npm, imported in Sass files. Must run `npm install` before building or styles will fail to compile. + +### 5. Sass Configuration + +Uses `sass-embedded` implementation (see `_config.yml:78`). If you encounter Sass compilation errors, ensure this gem is installed. + +### 6. Language/Locale Handling + +The site uses `lang` variable for internationalization: +- Default: `en` (set in `_config.yml:81`) +- Per-page: Set `lang: ""` in front matter +- Used in templates to fetch language-specific navigation data + +### 7. Breadcrumbs Configuration + +Breadcrumbs are enabled globally (`breadcrumbs: true` in `_config.yml:18`) but can be controlled per-page. Some pages set `breadcrumbColor` to customize appearance. + +## File and Directory Conventions + +### File Naming + +- **Markdown files**: Use lowercase with hyphens (e.g., `github-git-cheat-sheet.md`) +- **Directories**: Lowercase, use underscores for language variants (e.g., `pt_BR`, `zh_CN`) +- **Layouts/includes**: Lowercase with hyphens (e.g., `cheat-sheet.html`) + +### Front Matter Requirements + +Minimum front matter for content pages: +```yaml +--- +layout: default +title: "Page Title" +redirect_to: false +--- +``` + +For cheat sheets: +```yaml +--- +layout: cheat-sheet +redirect_to: false +title: "Cheat Sheet Title" +byline: "Brief description" +leadingpath: ../../ # Relative path to root for assets +--- +``` + +### Excluded from Build + +Per `_config.yml:47-59`, these are excluded from Jekyll build: +- `bin/` +- `Gemfile*` +- `node_modules/` +- `Rakefile` +- `README.md` +- `script/` +- `vendor/` +- `package.json` +- `package-lock.json` + +Don't reference these files from content pages. + +## Code Style and Patterns + +### HTML/Liquid + +- **Indentation**: 2 spaces +- **Liquid tags**: Space inside delimiters: `{% if condition %}` not `{%if condition%}` +- **Primer utilities**: Prefer utility classes over custom CSS +- **Semantic HTML**: Use appropriate elements (`
`, `