Contributing to AsiBackbone Learning

Thank you for your interest in contributing to AsiBackbone/Learning.

This repository is intended to be a community-maintained living tutorial for practical .NET architecture, governed execution, policy-driven systems, secure application design, AI integration, and related architectural patterns.

Contributions do not need to be large to be useful. A clearer explanation, corrected example, improved diagram, new lab, alternative implementation, or well-reasoned architecture critique can all materially improve the project.

Quick Contribution

For a typo, broken link, or narrow wording fix, the contribution path is intentionally short:

Edit the affected file directly on GitHub or in a short-lived branch.
Open a focused pull request describing the correction.
Let the automated checks run:
- Documentation Validation (docs-validation) builds the DocFX site with warnings treated as errors.
- Link Validation (link-validation) checks Markdown links for broken or invalid targets, including the #anchor part, so renaming a heading also means updating the links that point at it.
- Sample Validation (samples-validation) restores, builds, and tests the executable samples through the repository's explicit Microsoft.Testing.Platform runner; it runs on every pull request.
Address review comments if needed. Once the checks and review are satisfied, the change can be merged.

Documentation and educational contributions are accepted under CC BY 4.0; executable sample projects and source files under samples/ are accepted under the MIT License. See LICENSING.md for component-specific details.

For larger contributions such as tutorials, samples, labs, diagrams, new architectural patterns, or substantial restructuring, continue with Before You Start and the detailed guidance below.

Project Philosophy

A core principle of this repository is:

Read it. Run it. Question it. Improve it.

The goal is not to enforce one architectural doctrine.

The goal is to help developers understand problems, compare approaches, study tradeoffs, and connect architectural ideas to working implementations.

Where appropriate, tutorials should remain useful even to readers who never install the AsiBackbone package or use NetCoreApplicationTemplate.

Ways to Contribute

Contributions may include:

New tutorials
Corrections and clarifications
Minimal code examples
Architecture diagrams
Hands-on labs
Alternative implementations
Failure-mode analysis
Security or governance examples
ASP.NET Core examples
AI integration examples
Architecture critiques
Documentation improvements
Accessibility improvements
Cross-links to relevant implementation examples
Requests for new learning topics
Tests for tutorial or lab code
Fixes for outdated examples
Improvements to DocFX navigation or presentation

Small contributions are welcome.

Before You Start

For a small correction, typo, broken link, or narrow improvement, opening a pull request directly is usually appropriate.

For larger work, such as:

a new tutorial,
a new architectural pattern,
a substantial lab,
a major documentation restructuring,
a new category of examples,
or a proposal that changes the project's learning model,

please consider opening an Issue or Discussion first.

This helps avoid duplicated work and gives contributors an opportunity to refine the idea before investing significant effort.

Issues vs. Discussions

Use Issues for concrete work such as:

Broken documentation
Incorrect examples
Missing tests
Tutorial defects
Requested implementation work
Outdated links
DocFX problems
Clearly scoped enhancements

Use Learning Discussions for broader or exploratory topics such as:

Architecture questions
Tutorial proposals
Alternative patterns
Design debates
"How would you model this?" questions
Community learning ideas
Topics that may eventually become tutorials or labs

Choose the category that best matches the conversation:

Q&A — questions about .NET architecture, governed execution, security, AI integration, tutorials, samples, and other Learning topics.
Architecture & Patterns — architectural approaches, design tradeoffs, alternative patterns, governance models, and implementation debates.
Tutorial Ideas — proposals for tutorials, labs, examples, learning paths, or future educational material.
Show and tell — projects, experiments, adaptations, diagrams, or implementations inspired by Learning concepts and patterns.

Use AsiBackbone Organization Discussions when a topic genuinely spans multiple AsiBackbone repositories or concerns the organization as a whole.

A useful flow is:

Question
   ↓
Discussion
   ↓
Experiment or competing approaches
   ↓
Tutorial or documentation contribution
   ↓
Working example
   ↓
Feedback
   ↺

Contribution Principles

1. Teach the Problem Before the Product

Whenever practical, begin with the architectural problem rather than a package API.

A tutorial should explain why the problem exists before showing how a specific implementation addresses it.

Prefer:

Problem
   ↓
Common or naive implementation
   ↓
Failure mode or limitation
   ↓
Architectural pattern
   ↓
Minimal example
   ↓
Tradeoffs and alternatives
   ↓
Working repository example

over documentation that begins and ends with package installation instructions.

2. Keep Teaching Examples Small

The full AsiBackbone and NetCoreApplicationTemplate repositories already contain realistic complexity.

Examples in this repository should be intentionally small enough that the architectural lesson remains visible.

Avoid adding infrastructure or abstractions that are not necessary to teach the concept.

3. Separate Pattern From Implementation

Where useful, distinguish among:

Architecture Pattern — the general idea
Minimal Teaching Example — the simplified demonstration
Working Repository Example — the fuller implementation in another AsiBackbone repository

Do not duplicate large portions of canonical implementation documentation when a direct reference will serve better.

4. Explain Tradeoffs

Strong architectural documentation should explain when a pattern helps and when it may not.

Where appropriate, include:

Benefits
Costs
Complexity
Failure modes
Alternatives
Cases where the pattern is unnecessary

5. Alternatives Are Welcome

Architectural disagreement can be educational.

Contributions may present approaches that differ from the current AsiBackbone implementation when those approaches are:

Technically grounded
Clearly explained
Presented in good faith
Explicit about tradeoffs
Clearly identified as alternatives where necessary

Architectural Status Labels

When architectural status materially affects how a page should be interpreted, use one visible line near the page title or learning objective:

**Pattern classification:** <status>

Use one of these values:

Canonical Pattern — aligned with the current architecture of one or more AsiBackbone organization repositories.
Alternative Pattern — a viable different approach, or a comparison centered on an approach that intentionally differs from the current canonical organization pattern.
Experimental — exploratory architecture that tests or extends boundaries without claiming an established organization pattern or production-ready design. Experimental pages should state important assumptions, unknowns, and limits explicitly.
General learning material — educational material for which no stronger architectural-status claim is necessary.

Do not combine statuses into ad hoc labels such as General learning material — Experimental. Choose the single status that most affects interpretation. A navigation page, lab, exercise, or other document may omit the field entirely when classification would add no useful information.

These labels are descriptive, not quality rankings. Canonical does not mean universally correct, Alternative does not mean inferior, Experimental does not mean low quality, and General learning material does not mean unimportant. An alternative does not need to be treated as incorrect merely because it differs from the canonical implementation.

Page Orientation Metadata

Substantive learning pages should place orientation metadata immediately after the page title in this canonical order:

Learning objective
Pattern classification
Difficulty
Prerequisites

Write each field as its own bold-labeled paragraph, with a blank line between fields. Use None when a page is a suitable starting point, and link directly to prerequisite material when prior reading is expected. Navigation pages, indexes, labs, exercises, or other documents may omit fields that would add no useful guidance.

6. Preserve Project Boundaries

Do not present the Learning repository as:

A compliance certification
A legal standard
A security guarantee
An AI model
An AGI or ASI implementation
A robotics controller
A replacement for application-specific security review

Examples should not imply that using a demonstrated pattern automatically satisfies legal, regulatory, safety, or compliance obligations.

7. Keep Execution Ownership Clear

For governance and AI-related examples, preserve a clear distinction between proposed intent, governance decisions, authority, and execution.

A useful design principle is:

The model may propose. The host retains execution authority.

Do not describe the learning examples as granting unrestricted execution authority to AI systems.

Tutorial Guidelines

A strong tutorial will usually contain some combination of the following:

Problem

Describe the architectural problem in practical terms.

Why It Matters

Explain the consequences of solving the problem poorly.

Common or Naive Approach

Show a recognizable implementation that makes the problem easy to understand.

Failure Mode or Limitation

Explain why the simpler approach may be insufficient.

Architectural Pattern

Introduce the pattern being taught.

Minimal Example

Provide the smallest practical implementation that demonstrates the pattern.

Walkthrough

Explain how the example works.

Tradeoffs

Describe costs, limitations, and alternatives.

When Not to Use It

Identify situations where the pattern may be unnecessary or inappropriate.

Working Example

Link to the relevant AsiBackbone or NetCoreApplicationTemplate implementation when one exists.

Further Questions

Where useful, leave readers with unresolved questions or possible experiments.

Check Your Understanding

Substantive tutorials should normally end with a short Check Your Understanding self-assessment.

Keep the checklist capability-based rather than trivia-based. Prefer items that ask whether the learner can explain a boundary, identify responsibility, demonstrate an invariant, compare alternatives, or reason about a failure path.

A useful checklist usually contains four to seven items such as:

Explain the architectural boundary in your own words.
Identify which component owns the decision and which owns the side effect.
Demonstrate the important failure path or invariant.
Explain when a simpler architecture would be sufficient.

The checklist is reflective guidance, not a quiz, score, certification, or claim that one implementation is the only correct solution.

Not every tutorial must contain every section, but contributions should prioritize clarity and learning value.

Apply Usage Boundaries and ADR Links Selectively

Usage-boundary guidance should be explicit when a reader could reasonably over-apply the demonstrated architecture. A Pattern Card's Prefer something simpler when field may be enough for a compact tutorial; use a dedicated When Not to Use It, Use a Simpler Approach When, or equivalent section when the tradeoff needs more explanation.

Where practical, name the simpler or framework-native alternative rather than only saying that the pattern may be excessive. Examples include an ordinary application service, ASP.NET Core authorization or validation, one EF Core unit of work, or a single host-owned AI gateway when those mechanisms preserve the required boundary with less machinery.

When a working implementation has an Architecture Decision Record that directly explains the repository-specific choice, link it as a separate source of rationale:

Learning pattern
    = reusable architectural reasoning

Working implementation
    = current code, configuration, tests, and operational behavior

Architecture Decision Record
    = repository-specific context, decision, alternatives, and consequences

Do not add ADR links merely for link density. A related ADR should help the reader understand why a working repository selected or retained a particular implementation direction. The ADR does not make that local choice universally required, and a Learning page does not need an ADR link when no direct decision record exists.

Lab Guidelines

Labs should encourage active reasoning rather than simply repeating tutorial steps.

A lab may include:

A partially implemented application
A deliberately weak architecture to improve
Failing tests
A policy-design problem
A security-boundary exercise
An AI tool-execution scenario
A decision-pipeline exercise
A debugging or review task

A good lab should clearly state:

The learning objective
Starting conditions
Constraints
Expected outcome
How to validate the result

Labs should also define architectural acceptance criteria so learners can distinguish a program that merely runs from one that preserves the boundary the exercise is intended to teach.

Use community/lab-acceptance-criteria-template.md as the reusable authoring starting point. Specialize the criteria to the lab rather than copying them mechanically.

Useful criteria commonly verify that:

The required architectural boundary is demonstrable.
A prohibited execution or authority path is absent.
Relevant decision or lifecycle evidence is preserved.
At least one important failure path is observable.
The architectural invariant is verified by a test, deterministic observation, or other explicit evidence.
The learner can explain a meaningful tradeoff or alternative.

Acceptance criteria should describe architectural outcomes, not prescribe one code shape when multiple implementations can preserve the same invariant.

Existing automated tests may contribute evidence, but passing tests should not be treated as the only definition of successful learning.

Where solutions are included, consider keeping them separate from the exercise so learners can attempt the problem first.

Code Contributions

For code examples:

Prefer clear, idiomatic C# and .NET patterns.
Keep dependencies minimal unless a dependency is central to the lesson.
Avoid unnecessary abstractions.
Use meaningful names.
Prefer examples that compile and can be tested.
Add tests when the lesson depends on behavioral correctness.
For executable samples, cover every documented outcome and stable reason code, prove negative side-effect invariants, and include relevant invalid-input and cancellation boundaries with descriptive test names.
Avoid embedding real credentials, secrets, tokens, connection strings, or personally identifiable information.
Use obviously fictional or placeholder values where examples require identifiers or sensitive-looking data.
When adding, renaming, or removing an executable sample, update both sample catalogs. Add or revise its repository-facing entry in samples/README.md, and update docs/samples/index.md with its learning objective, difficulty, key invariant, run command, and canonical README link so the published sample guide remains current.

Code should optimize for understanding first, while still modeling responsible engineering practice.

Documentation Style

Documentation should generally be:

Clear
Direct
Technically grounded
Accessible to developers at different experience levels
Explicit about assumptions
Honest about tradeoffs
Careful about overclaiming

Avoid unnecessary promotional language.

Prefer statements that explain what a pattern does over statements that declare it universally superior.

Publishing Authored Articles

Learning supports two related publication cases without creating a second publishing system:

Selected curriculum documents may continue to opt into authored metadata and RSS when they are substantive enough to stand on their own.
Standalone technical publications intended for direct external discovery should live under docs/articles/<year>/<slug>.md. Those pages form the append-only Articles archive and carry a deliberate permanent-URL contract.

Publication metadata does not by itself make a curriculum page part of the permanent Articles archive. The stable publication contract comes from publishing the standalone document under docs/articles/.

Problem-Oriented Article Planning

Use the Problem-Oriented Standalone Article Backlog when selecting future standalone publications. The backlog prioritizes recognizable developer/search problems that already have substantial Learning material behind them; it is not a quota, publishing calendar, or substitute for the curriculum roadmap.

A backlog candidate should become implementation work only after a dedicated issue is opened for that specific article. Use that issue to refine the reader problem, working title, permanent slug, supporting Learning sources, and the article's distinct contribution before drafting under docs/articles/<year>/. This keeps editorial prioritization separate from implementation tracking and avoids converting curriculum pages into articles merely to increase page count.

Articles vs. Curriculum Material

Use the distinction below when choosing where a new document belongs.

Curriculum material	Article
Part of a learning progression	Standalone technical argument
May have prerequisites	Must be understandable without curriculum prerequisites
Teaches a concept systematically	Makes one useful argument completely
May move if the curriculum is reorganized	Keeps its published `/articles/<year>/<slug>` URL
Optimized for teaching sequence and internal navigation	Optimized for direct discovery, citation, and external linking

An article may link to tutorials, samples, labs, ADRs, or implementation repositories for deeper study, but those references should not be required to understand the article itself.

Contextual Linking Convention

Standalone articles and substantive curriculum pages should form small topical clusters through links that answer the reader's next likely question. This is contextual navigation inside the content, not another global navigation system.

A useful progression is:

Problem-oriented article
       ↓
Architecture explanation or comparison
       ↓
Tutorial
       ↓
Runnable sample / invariant tests
       ↓
Lab

Do not force every page through every stage. Add only destinations that materially deepen the page at the point where the reader is likely to need them.

For contextual links:

Explain why the destination is relevant instead of using generic Related or click here anchor text.
Keep the cluster small; two to five strong destinations are usually more useful than a long list of loosely related pages.
Add reciprocal links only when the source page provides a useful problem-first entry point or genuinely clarifies the destination. Do not manufacture symmetry for search optimization.
Keep standalone articles understandable without following the links; contextual destinations deepen the argument rather than complete missing prerequisites.
Prefer relative links for Learning documentation and stable repository links for executable samples that live outside docs/.

Avoid boilerplate blocks that enumerate whole site sections. The goal is to let a reader move naturally from a concrete problem into the most relevant explanation, comparison, runnable evidence, or exercise without returning to the site root.

Publication Metadata Contract

Articles reuse the existing authored-publication metadata and RSS generator. Do not introduce a separate article feed, metadata format, CMS, or source-of-truth copy.

The supported contract is:

---
title: When ASP.NET Core Authorization Is Enough
author: Christopher D. Cavell
published: "2026-08-14"
updated: "2026-08-20"
summary: Built-in policies and handlers cover more than teams sometimes assume.
feed: true
---

The fields mean:

title is the canonical article title.
author is the displayed author and RSS creator attribution.
published is the original publication date in double-quoted "YYYY-MM-DD" format so YAML processors preserve it as a string.
updated is optional, uses the same double-quoted date format, must not be earlier than published, and should be changed only for a substantive revision, not routine formatting or link maintenance. When present, the feed emits the date as an Atom atom:updated timestamp at 00:00:00Z; RSS pubDate continues to represent the original published date.
summary is the concise article description used by the feed.
feed controls RSS participation explicitly. Only feed: true publishes an item.

For a feed-enabled article, title, author, published, and summary are required. Publication remains opt-in even when some metadata is present. The feed generator validates required fields, date formats, canonical generated HTML targets, and writes docs/_site/feed.xml.

Permanent Article Paths

Publish standalone articles with the intentionally simple year-and-slug structure:

docs/articles/2026/authorization-check-runs-too-late.md
        ↓
https://asibackbone.github.io/Learning/articles/2026/authorization-check-runs-too-late.html

The year is the article's original publication year. A later substantive revision may add or change updated, but it does not move the article into a new year.

Once a page has been publicly released under /articles/<year>/<slug>, treat that URL as append-only:

Do not rename the slug.
Do not move the article into another content category.
Do not renumber it.
Do not move it into another year.
Do not change its URL merely because the Learning curriculum is reorganized.

If an exceptional move becomes unavoidable, preserve the old public address with the safest redirect or compatibility mechanism supported by the current DocFX and GitHub Pages setup. The normal rule is simpler: published article URLs do not move.

Do not introduce category directories such as articles/security/, articles/governance/, or articles/ai/ merely to mirror the documentation hierarchy. The year/slug structure is deliberately resistant to curriculum reorganization.

Problem-Oriented Titles and Slugs

Lead with a developer problem rather than repository vocabulary. Use lowercase kebab-case slugs that remain meaningful outside the AsiBackbone organization.

Prefer:

authorization-check-runs-too-late
ci-badge-does-not-prove-package-integrity
when-a-short-lived-token-is-not-enough
why-your-ai-tool-call-is-only-a-proposal

over:

decision-before-execution-pattern
governed-execution-model
capability-scoped-authority
asi-backbone-governance

Repository-specific terminology may appear after the practical problem has been established and should be distinguished from broader established concepts when that distinction matters.

Canonical Publication Host

The canonical copy of an article is the version published by the Learning site under https://asibackbone.github.io/Learning/. If an article is later cross-posted elsewhere, keep Learning as the authoritative source and use canonical attribution back to the Learning URL when the external platform supports it.

Do not maintain a second CMS or separately edited source-of-truth copy just to syndicate an article.

Article Publication Checklist

Before publishing a new standalone article, normally confirm that:

Article participation and feed-surface validity are separate concerns. Individual documents opt in only with feed: true, but the repository's published RSS surface is expected to contain at least one feed-enabled article. Generation intentionally fails when zero feed-enabled documents are found so accidental removal or disablement of the entire feed is visible during validation.

To build and inspect the publication surface locally, run from the repository root:

dotnet tool restore
dotnet tool run docfx docs/docfx.json --warningsAsErrors
dotnet run --file tools/generate-feed.cs -- --self-test
dotnet run --file tools/generate-feed.cs

Then inspect the rendered article metadata under docs/_site/ and the generated docs/_site/feed.xml.

Building Documentation Locally

The Learning documentation site is generated with DocFX.

The repository pins the DocFX version through .config/dotnet-tools.json, so contributors should use the repository-local .NET tool manifest rather than relying on a separately installed global DocFX version.

To match the repository's documentation-validation workflow as closely as practical, use the .NET 10 SDK.

From the repository root, restore the pinned tools:

dotnet tool restore

Build the documentation using the same strict validation used by CI:

dotnet tool run docfx docs/docfx.json --warningsAsErrors

A successful build generates the static documentation site under:

docs/_site/

Warnings are treated as errors intentionally. Contributors should resolve DocFX warnings rather than relying on CI to accept a locally warning-producing build.

Updating DocFX and the Custom Modern Template

Learning overrides the complete DocFX modern _master.tmpl so the site can add metadata and publishing behavior that the current template does not expose through a head partial. That control creates a maintenance obligation whenever the pinned DocFX version changes.

The reviewed upstream baseline is recorded in docs/templates/docfx-template-baseline.json. CI validates that its DocFX version matches .config/dotnet-tools.json, that the local _master.tmpl comment declares the same baseline, and that docs/docfx.json still composes the upstream modern template with the local templates override.

Run the consistency check locally with:

dotnet run --file tools/validate-docfx-template-baseline.cs

When upgrading DocFX:

Update .config/dotnet-tools.json to the intended DocFX version.
Obtain the modern _master.tmpl corresponding to that exact DocFX release and diff it against the baseline used by docs/templates/layout/_master.tmpl.
Re-evaluate whether a complete _master.tmpl override is still necessary. If the target DocFX release provides a supported head-extension mechanism that covers the site's needs, prefer removing the full-template override and its synchronization burden.
Reapply only the intentional Learning customizations to the new upstream layout. Preserve required site behavior such as the language attribute, search/navigation metadata, verification tags, descriptions, canonical URLs, structured data, RSS discovery, contribution links, and previous/next article behavior where the target template supports them.
Only after that review, update docs/templates/docfx-template-baseline.json and the version comment at the top of docs/templates/layout/_master.tmpl.
Run the baseline validator, build DocFX with warnings as errors, generate the RSS feed, and run tools/validate-doc-metadata.cs.
Inspect representative generated HTML under docs/_site/, including navigation/search behavior and the custom <head> output, before merging the upgrade.

The version-consistency check cannot prove that an upstream diff was reviewed. Its purpose is to make a package-only DocFX bump fail visibly until the custom-template baseline is deliberately reconciled.

Preview the Documentation Locally

After building the site, start the DocFX local server with:

dotnet tool run docfx serve docs/_site

Then open:

http://localhost:8080

Stop the local server with Ctrl+C.

For a combined build-and-preview workflow, you may also run:

dotnet tool run docfx docs/docfx.json --warningsAsErrors --serve

When documentation content, navigation, links, diagrams, or DocFX configuration changes, review the rendered site locally when practical before opening a pull request.

Before submitting documentation changes, rerun:

dotnet tool run docfx docs/docfx.json --warningsAsErrors

This is the closest local equivalent to the repository's required Build DocFX documentation validation check.

Diagrams

Diagrams are encouraged when they make an architectural boundary or sequence easier to understand.

Useful diagram types include:

Request-flow diagrams
Sequence diagrams
Trust-boundary diagrams
Policy evaluation flows
Capability-grant flows
AI tool-execution gateways
Middleware pipelines
C4-style architecture diagrams

Mermaid is preferred when practical because diagrams remain reviewable as text.

Image-based diagrams are also acceptable when they provide clear value.

Accessibility

Accessibility is part of documentation quality.

As the Learning repository adds diagrams, images, tables, media, custom styling, and interactive content, contributors should preserve an equivalent learning path for readers who use assistive technology, keyboard navigation, zoom, high-contrast settings, or other accessibility features.

When contributing documentation:

Provide meaningful alternative text for informative images.
Use empty alternative text only for images that are truly decorative.
Accompany important diagrams with surrounding prose that explains the sequence, relationships, boundaries, or conclusions being illustrated.
Do not rely on color, shape, position, or animation alone to communicate meaning.
Prefer ordinary text over images of text when practical.
Use descriptive headings and meaningful link text.
Keep heading levels logically structured rather than choosing them only for visual appearance.
Use tables for genuinely tabular information rather than page layout, and keep table structures as simple as practical.
Ensure code examples and architectural flows remain understandable without depending on syntax color or visual position alone.
Review custom colors and styling for adequate contrast.
Review custom layouts at increased zoom and narrow viewport widths.
Check both light and dark presentation when custom styling is introduced and both modes are supported.
Ensure custom interactive content can be operated with a keyboard, preserves visible focus, and does not trap keyboard focus.
Provide appropriate captions, transcripts, or equivalent alternatives if audio or video content is introduced.

Mermaid and text-based diagrams remain useful because their source is reviewable as text, but diagram source should not be treated as a substitute for a clear prose explanation.

A reader who cannot perceive a diagram should still be able to understand the architectural lesson from the surrounding material.

For substantial new diagrams, media, interactive components, or theme customizations, additional automated or manual accessibility testing may be appropriate.

Links to Working Repositories

When a tutorial maps to an existing implementation, link directly to the most relevant file, folder, documentation page, or ADR.

Primary implementation repositories include:

Avoid copying large implementation sections into Learning when a maintained source already exists elsewhere.

Branches

For contributed work, use a short descriptive branch name when practical.

Examples:

tutorial/policy-context
tutorial/decision-before-execution
lab/ai-tool-gateway
docs/improve-contribution-guide
fix/broken-learning-link
diagram/capability-flow

Exact naming is not mandatory, but descriptive names make review easier.

Commit Messages

Prefer concise commit messages that describe the change.

Examples:

docs: add policy context tutorial
docs: clarify host-owned execution boundary
feat: add beginner decision pipeline lab
fix: correct capability token example
test: add validation for tutorial sample

Large contributions may use multiple focused commits when that improves reviewability.

Pull Requests

A pull request should explain:

What changed
Why the change is useful
Which learning area it affects
How the contribution was validated
Whether it represents a canonical or alternative pattern when that distinction matters

For code-based tutorials or labs, include relevant build or test results.

For diagrams or documentation-only contributions, describe how you verified links, rendering, or navigation when applicable.

Keep pull requests focused where practical.

A focused tutorial improvement is easier to review than a large unrelated collection of changes.

Suggested Pull Request Summary

A simple pull request description may use:

## Summary

Briefly explain what this contribution adds or changes.

## Learning Value

Explain what readers should understand or be able to do after this change.

## Changes

- Change one
- Change two
- Change three

## Validation

Describe how the documentation, example, lab, or code was checked.

## Pattern Classification

- [ ] Canonical Pattern
- [ ] Alternative Pattern
- [ ] General Learning Material
- [ ] Not applicable

This structure is optional unless a future repository template makes it mandatory.

Review Expectations

Review may consider:

Technical correctness
Learning value
Clarity
Scope
Maintainability
Consistency with project boundaries
Whether claims are appropriately qualified
Whether alternatives and tradeoffs are represented fairly
Whether the example duplicates material that belongs in another repository
Whether code or diagrams can be simplified

Review comments should focus on improving the contribution rather than proving one person right.

Changes Requested During Review

Contributors should expect that tutorials may require revision.

Educational material often needs refinement even when the underlying code is technically correct.

Requests may include:

Simplifying an example
Clarifying assumptions
Adding a tradeoff section
Correcting overbroad claims
Separating canonical and alternative patterns
Linking to the real implementation
Adding validation or tests
Improving accessibility or readability

These requests are part of maintaining a useful learning resource.

Security

Do not report security vulnerabilities through a public Issue when disclosure could create risk.

Follow the security reporting guidance provided by the repository or AsiBackbone organization when available.

Never include:

Real passwords
API keys
Signing keys
Access tokens
Private certificates
Production connection strings
Confidential organization information
Personal data

in tutorial examples, commits, Issues, Discussions, or pull requests.

Contribution Licensing

Contributions are accepted under the license applicable to the material being modified:

Documentation and educational content: CC BY 4.0
Executable sample code: MIT
Code snippets included in documentation: additionally available under MIT

Contributors must have the right to submit contributed material under the applicable license.

Code of Conduct

All participation is subject to the repository's Code of Conduct.

Technical disagreement, skepticism, and architecture criticism are welcome.

Harassment, personal attacks, intimidation, discrimination, or deliberate disruption are not.

Recognition

Contributions of all sizes are valued.

The project may recognize contributors through Git history, release notes, contributor listings, documentation acknowledgments, or other appropriate mechanisms as the repository evolves.

Questions

If you are unsure whether an idea belongs in the repository, start an AsiBackbone Organization Discussion.

If you have identified a concrete problem, open an Issue.

If you already have a focused improvement, a pull request is welcome.

The project is intended to evolve through exactly this kind of participation.