📚 LearnStack Documentation Hub

Welcome to the LearnStack documentation and automation directory!

📖 Documentation Files

🚀 Deployment & Operations

• DEPLOYMENT.md - Complete Azure App Service deployment guide
• RELEASES.md - Versioning, releases, and semantic versioning guide
• PIPELINE.md - CI/CD pipeline architecture and visual workflows
• QUICK-REFERENCE.md - Quick reference card for common tasks

📝 Project Documentation

• ../CHANGELOG.md - Version history and notable changes

🔧 GitHub Actions Workflows

Workflow Files (.github/workflows/)

azure-app-service.yml

Automated CI/CD pipeline for Azure deployment with semantic versioning.

Triggers:

• Automatic: Push to main branch
• Manual: Workflow dispatch with version bump selection

Features:

• ✅ Builds .NET 10 Blazor application
• 🧪 Runs automated tests
• 🚀 Deploys to Azure App Service
• 🏷️ Creates semantic versioned releases
• 📦 Publishes GitHub releases with auto-generated notes

Configuration Required:

• AZURE_WEBAPP_PUBLISH_PROFILE secret
• AZURE_WEBAPP_NAME environment variable

🎯 Quick Start

First Time Setup

1. Read the deployment guide:

   cat .github/DEPLOYMENT.md

2. Configure Azure:

   • Create App Service
   • Download publish profile
   • Add to GitHub secrets

3. Deploy:

   git push origin main

Daily Usage

Need quick help? Check the Quick Reference Card!

# Deploy with automatic versioning
git commit -m "feat: new feature"
git push origin main

# Manual deployment with version control
gh workflow run azure-app-service.yml -f version_bump=minor

📊 Documentation Map

LearnStack/
├── README.md                          # Main project README
├── CHANGELOG.md                       # Version history
└── .github/
    ├── README.md                      # This file
    ├── DEPLOYMENT.md                  # Azure deployment guide
    ├── RELEASES.md                    # Versioning & releases
    ├── PIPELINE.md                    # CI/CD architecture
    ├── QUICK-REFERENCE.md            # Quick reference card
    ├── instructions/
    │   └── copilot.instructions.md   # Copilot customization
    └── workflows/
        └── azure-app-service.yml     # Main CI/CD workflow

🎨 Visual Guides

Deployment Flow

See PIPELINE.md for visual diagrams of:

• Complete CI/CD pipeline flowchart
• Version decision tree
• Release timeline
• Environment flow
• Success metrics

Version Strategy

See RELEASES.md for:

• Semantic versioning rules
• Release note templates
• Commit message conventions
• Best practices

🔗 Quick Links

Documentation	Purpose
🚀 Deployment	How to deploy to Azure
🏷️ Releases	Version management
🔄 Pipeline	CI/CD architecture
⚡ Quick Ref	Common commands
📝 Changelog	Version history

📋 Common Tasks

Deployment Tasks

# Standard deployment
git push origin main

# Force version bump
gh workflow run azure-app-service.yml -f version_bump=major

# Check deployment status
gh run list --workflow=azure-app-service.yml

Version Management

# Current version
git describe --tags --abbrev=0

# All releases
gh release list

# View specific release
gh release view v1.0.0

Troubleshooting

# View workflow logs
gh run view [RUN_ID]

# Check Azure logs
az webapp log tail --name your-app-name --resource-group your-rg

See QUICK-REFERENCE.md for complete command reference.

🛠️ Maintenance

Regular Updates

• Review and update docs quarterly
• Keep workflow actions up to date
• Update examples with current best practices

When to Update Each Doc

File	Update When
DEPLOYMENT.md	Azure setup changes
RELEASES.md	Versioning strategy changes
PIPELINE.md	Workflow architecture changes
QUICK-REFERENCE.md	New common tasks added
CHANGELOG.md	Every release

🤝 Contributing

Documentation Improvements

Found an error or unclear section? Please:

1. Open an issue describing the problem
2. Or submit a PR with improvements
3. Or start a discussion with suggestions

Adding New Workflows

When adding new GitHub Actions workflows:

1. Add the workflow file to workflows/
2. Document it in this README
3. Add usage instructions to QUICK-REFERENCE.md
4. Update PIPELINE.md if it changes architecture

📞 Support

Documentation Support

• 📖 Read the relevant guide above
• 🔍 Search existing issues
• 💬 Start a discussion
• 🐛 Report doc issues

Deployment Support

• Check DEPLOYMENT.md troubleshooting section
• Review PIPELINE.md for architecture
• See QUICK-REFERENCE.md for common fixes

🎓 Learning Resources

GitHub Actions

• GitHub Actions Documentation
• Workflow syntax

Azure App Service

• Azure App Service docs
• Deploy .NET apps

Semantic Versioning

• SemVer Specification
• Conventional Commits

📊 Documentation Status

Document	Status	Last Updated
DEPLOYMENT.md	✅ Complete	2026-02-21
RELEASES.md	✅ Complete	2026-02-21
PIPELINE.md	✅ Complete	2026-02-21
QUICK-REFERENCE.md	✅ Complete	2026-02-21
CHANGELOG.md	✅ Complete	2026-02-21

---

🌟 Tips

💡 Bookmark these docs - You'll reference them often!

💡 Start with QUICK-REFERENCE - It has the most common commands

💡 Use the visual diagrams - PIPELINE.md has helpful flowcharts

💡 Follow conventional commits - Makes releases easier

💡 Test locally first - Before pushing to main

---

Documentation maintained by the LearnStack team

Questions? Open an issue or start a discussion!