feat(docs): restructure documentation with new framework and templates
- Archive old docs to docs-old/ for reference - Create new top-down documentation structure: * Platform Overview: purpose, audience, product structure * Components: individual platform components (Forgejo, Kubernetes, Backstage) * Getting Started: onboarding and quick start guides * Operations: deployment, monitoring, troubleshooting * Governance: ADRs, project history, compliance - Add DOCUMENTATION-GUIDE.md with writing guidelines and templates - Add component template (TEMPLATE.md) for consistent documentation - Simplify root README and move technical docs to doc/ folder - Update test configuration: * Exclude legacy content from markdown linting * Relax HTML validation for theme-generated content * Skip link checking for legacy content in test:links * Keep 'task test' clean for technical writers (100% pass) * Add 'task test:full' with comprehensive link checking - Update home page with corrected markdown syntax - Fix internal links in archived content BREAKING CHANGE: Documentation structure changed from flat to hierarchical top-down approach
This commit is contained in:
parent
2ec2efe9fc
commit
62999b41d0
196 changed files with 907 additions and 160 deletions
496
doc/README-developer.md
Normal file
496
doc/README-developer.md
Normal file
|
|
@ -0,0 +1,496 @@
|
|||
# Developer Guide - IPCEI-CIS Developer Framework
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Install [Devbox](https://www.jetify.com/devbox/):
|
||||
```bash
|
||||
curl -fsSL https://get.jetify.com/devbox | bash
|
||||
```
|
||||
|
||||
### Setup
|
||||
|
||||
1. Clone the repository
|
||||
2. Install dependencies:
|
||||
```bash
|
||||
task deps:install
|
||||
```
|
||||
3. Start devbox shell:
|
||||
```bash
|
||||
devbox shell
|
||||
```
|
||||
|
||||
Devbox automatically installs all required tools:
|
||||
- Hugo (v0.151.0+extended)
|
||||
- Go (v1.25.1)
|
||||
- Node.js (v24.10.0)
|
||||
- Dart Sass
|
||||
- htmltest
|
||||
- go-task
|
||||
|
||||
> **Note:** For content contributors, see [README-technicalWriter.md](./README-technicalWriter.md) for a simplified guide.
|
||||
|
||||
## 📚 Technology Stack
|
||||
|
||||
### Hugo (v0.151.0+extended)
|
||||
|
||||
Hugo is a fast static site generator. This project uses Hugo in extended mode with:
|
||||
- **Docsy Theme** (v0.12.0) - Documentation theme with responsive design
|
||||
- **Bootstrap 5.3.8** - UI framework
|
||||
- **PostCSS** - CSS processing
|
||||
|
||||
### Docsy Theme
|
||||
|
||||
Docsy is a Hugo theme optimized for technical documentation:
|
||||
- Multi-language support
|
||||
- Search functionality
|
||||
- Navigation menu system
|
||||
- Code syntax highlighting
|
||||
- Responsive design
|
||||
|
||||
Key directories:
|
||||
- `content/en/` - English content (Markdown files)
|
||||
- `layouts/` - Custom layout overrides
|
||||
- `assets/scss/` - Custom styles
|
||||
- `static/` - Static assets (images, etc.)
|
||||
|
||||
### LikeC4 (v1.43.0)
|
||||
|
||||
LikeC4 is used for interactive architecture diagrams:
|
||||
- C4 model-based architecture visualization
|
||||
- Web Components for embedding diagrams
|
||||
- Real-time preview during development
|
||||
|
||||
Architecture models:
|
||||
- `resources/edp-likec4/` - Platform architecture models
|
||||
- `resources/doc-likec4/` - Documentation platform models
|
||||
|
||||
LikeC4 tasks available:
|
||||
- `task likec4:generate` - Generate web components
|
||||
- `task likec4:validate` - Validate C4 models
|
||||
- `task likec4:update` - Update LikeC4 version
|
||||
|
||||
### Task (Taskfile)
|
||||
|
||||
Task is a task runner / build tool that replaces Makefiles. It uses `Taskfile.yml` for defining tasks.
|
||||
|
||||
## 🛠️ Development Workflow
|
||||
|
||||
### Using Task (Recommended)
|
||||
|
||||
View all available tasks:
|
||||
```bash
|
||||
task
|
||||
# or
|
||||
task --list
|
||||
```
|
||||
|
||||
Common tasks:
|
||||
|
||||
#### Development
|
||||
```bash
|
||||
task serve # Start Hugo dev server (http://localhost:1313)
|
||||
task build # Build production site
|
||||
task build:dev # Build development site
|
||||
task clean # Clean build artifacts
|
||||
```
|
||||
|
||||
#### Testing
|
||||
```bash
|
||||
task test # Run all tests
|
||||
task test:quick # Run quick tests (without link checking)
|
||||
task test:build # Test if Hugo builds successfully
|
||||
task test:markdown # Lint Markdown files
|
||||
task test:html # Validate HTML output
|
||||
task test:links # Check all links (internal & external)
|
||||
```
|
||||
|
||||
#### Dependencies
|
||||
```bash
|
||||
task deps:install # Install all dependencies
|
||||
task deps:update # Update all dependencies
|
||||
```
|
||||
|
||||
#### LikeC4
|
||||
```bash
|
||||
task likec4:generate # Generate web components from C4 models
|
||||
task likec4:validate # Validate C4 model syntax
|
||||
task likec4:update # Update LikeC4 to latest version
|
||||
```
|
||||
|
||||
#### Build & Test OCI Image
|
||||
```bash
|
||||
task build:oci-image # Build Docker/OCI image
|
||||
task test:oci-image # Build and test image
|
||||
```
|
||||
|
||||
#### CI/CD
|
||||
```bash
|
||||
task ci # Run full CI pipeline locally
|
||||
```
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
This project uses multiple automated tests for quality assurance.
|
||||
|
||||
### Test Configuration Files
|
||||
|
||||
- `.htmltest.yml` - Link checker configuration
|
||||
- `.htmlvalidate.json` - HTML validation rules
|
||||
- `.markdownlint.json` - Markdown linting rules
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
GitHub Actions runs these tests automatically on every push/PR via `.github/workflows/test.yml`.
|
||||
|
||||
### Local Development Workflow
|
||||
|
||||
**Before commit:**
|
||||
```bash
|
||||
task test:quick
|
||||
```
|
||||
|
||||
**Before push:**
|
||||
```bash
|
||||
task test
|
||||
```
|
||||
|
||||
## 🐳 Docker / Container Build
|
||||
|
||||
### Version Management
|
||||
|
||||
All tool versions are defined in `.env.versions` as the single source of truth:
|
||||
|
||||
```bash
|
||||
NODE_VERSION=24.10.0
|
||||
GO_VERSION=1.25.1
|
||||
HUGO_VERSION=0.151.0
|
||||
```
|
||||
|
||||
These versions are used in:
|
||||
- `devbox.json` - Local development (manual sync required)
|
||||
- `Dockerfile` - Build arguments with defaults
|
||||
- `.github/workflows/ci.yaml` - CI/CD pipeline (automatic)
|
||||
|
||||
**Updating versions:**
|
||||
|
||||
1. Edit `.env.versions`
|
||||
2. Manually sync `devbox.json`:
|
||||
```json
|
||||
{
|
||||
"packages": [
|
||||
"hugo@0.151.0",
|
||||
"go@1.25.1",
|
||||
"nodejs@24.10.0"
|
||||
]
|
||||
}
|
||||
```
|
||||
3. Rebuild: `devbox shell --refresh`
|
||||
|
||||
### Local Build
|
||||
|
||||
**Using Task (recommended):**
|
||||
|
||||
```bash
|
||||
task build:oci-image # Build OCI image
|
||||
task test:oci-image # Build and test
|
||||
```
|
||||
|
||||
This automatically loads versions from `.env.versions` and tags with `latest` and git commit hash.
|
||||
|
||||
**Helper script for manual builds:**
|
||||
|
||||
```bash
|
||||
source scripts/get-versions.sh
|
||||
# Shows Docker build command with correct versions
|
||||
```
|
||||
|
||||
**Manual build:**
|
||||
|
||||
```bash
|
||||
docker build --network=host \
|
||||
--build-arg NODE_VERSION=24.10.0 \
|
||||
--build-arg GO_VERSION=1.25.1 \
|
||||
--build-arg HUGO_VERSION=0.151.0 \
|
||||
-t ipceicis-developerframework:latest .
|
||||
```
|
||||
|
||||
**Test the image:**
|
||||
|
||||
```bash
|
||||
docker run -d -p 8080:80 --name hugo-test ipceicis-developerframework:latest
|
||||
curl http://localhost:8080
|
||||
docker stop hugo-test && docker rm hugo-test
|
||||
```
|
||||
|
||||
### Image Structure
|
||||
|
||||
- **Build Stage**: Node.js base, installs Go and Hugo
|
||||
- **Runtime Stage**: nginx:alpine serves static content (~50MB)
|
||||
|
||||
Build process:
|
||||
1. Install npm dependencies
|
||||
2. Download Hugo modules
|
||||
3. Build static site (`hugo --gc --minify`)
|
||||
4. Copy to nginx container
|
||||
|
||||
### CI/CD Pipeline
|
||||
|
||||
`.github/workflows/ci.yaml` automatically:
|
||||
1. Extracts versions from devbox environment
|
||||
2. Builds multi-arch images (amd64 + arm64)
|
||||
3. Pushes to container registry
|
||||
|
||||
**Required GitHub Secrets:**
|
||||
- `PACKAGES_USER` - Registry username
|
||||
- `PACKAGES_TOKEN` - Registry token/password
|
||||
|
||||
#### CI/CD
|
||||
```bash
|
||||
task ci # Run full CI pipeline locally
|
||||
```
|
||||
|
||||
### Using NPM Scripts (Alternative)
|
||||
|
||||
If you prefer NPM:
|
||||
```bash
|
||||
npm test # All tests
|
||||
npm run test:quick # Quick tests
|
||||
npm run test:build # Build test
|
||||
npm run test:markdown # Markdown linting
|
||||
npm run test:html # HTML validation
|
||||
npm run test:links # Link checking
|
||||
```
|
||||
|
||||
### Using Hugo Directly
|
||||
|
||||
```bash
|
||||
# Development server
|
||||
hugo server
|
||||
|
||||
# Production build
|
||||
hugo --gc --minify
|
||||
|
||||
# Check version
|
||||
hugo version
|
||||
```
|
||||
|
||||
## 📁 Project Structure
|
||||
|
||||
```
|
||||
.
|
||||
├── content/ # Content files (Markdown)
|
||||
│ └── en/ # English content
|
||||
│ ├── docs/ # Documentation
|
||||
│ └── blog/ # Blog posts
|
||||
├── resources/ # LikeC4 architecture models
|
||||
│ ├── edp-likec4/ # Platform architecture (C4 models)
|
||||
│ └── doc-likec4/ # Documentation platform architecture
|
||||
├── layouts/ # Custom HTML templates
|
||||
│ └── shortcodes/ # Custom shortcodes (e.g., likec4-view)
|
||||
├── static/ # Static files
|
||||
│ └── js/ # JavaScript (LikeC4 webcomponents)
|
||||
├── assets/ # Assets (SCSS, images)
|
||||
├── public/ # Generated site (not in Git)
|
||||
├── hugo.toml # Hugo configuration
|
||||
├── go.mod # Hugo modules (Docsy theme)
|
||||
├── Taskfile.yml # Task definitions
|
||||
├── package.json # NPM dependencies & scripts
|
||||
├── devbox.json # Devbox configuration
|
||||
├── .env.versions # Version definitions (SSOT)
|
||||
├── Dockerfile # Multi-stage container build
|
||||
├── README.md # Main README
|
||||
├── README-developer.md # This file
|
||||
├── README-technicalWriter.md # Guide for content contributors
|
||||
├── README-likec4.md # LikeC4 architecture modeling guide
|
||||
└── RELEASE.md # Release process documentation
|
||||
```
|
||||
|
||||
## 📝 Content Creation
|
||||
|
||||
### Creating New Pages
|
||||
|
||||
```bash
|
||||
# Using Hugo
|
||||
hugo new docs/concepts/my-page.md
|
||||
hugo new blog/my-post.md
|
||||
|
||||
# Or create manually in content/en/
|
||||
```
|
||||
|
||||
### Front Matter
|
||||
|
||||
Every content file needs front matter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "My Page Title"
|
||||
description: "Page description"
|
||||
date: 2025-10-23
|
||||
weight: 10 # Order in navigation
|
||||
---
|
||||
|
||||
Your content here...
|
||||
```
|
||||
|
||||
### Using Docsy Shortcodes
|
||||
|
||||
Docsy provides helpful shortcodes:
|
||||
|
||||
#### Tabbed Panes
|
||||
```markdown
|
||||
{{</* tabpane */>}}
|
||||
{{</* tab "Tab 1" */>}}
|
||||
Content for tab 1
|
||||
{{</* /tab */>}}
|
||||
{{</* tab "Tab 2" */>}}
|
||||
Content for tab 2
|
||||
{{</* /tab */>}}
|
||||
{{</* /tabpane */>}}
|
||||
```
|
||||
|
||||
#### Code Blocks
|
||||
```markdown
|
||||
{{</* code lang="yaml" */>}}
|
||||
key: value
|
||||
{{</* /code */>}}
|
||||
```
|
||||
|
||||
#### Alerts
|
||||
```markdown
|
||||
{{</* alert title="Note" */>}}
|
||||
Important information
|
||||
{{</* /alert */>}}
|
||||
```
|
||||
|
||||
#### LikeC4 Architecture Diagrams
|
||||
```markdown
|
||||
{{</* likec4-view view="overview" project="architecture" title="System Overview" */>}}
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `view` - View ID from C4 model
|
||||
- `project` - `"architecture"` or `"documentation-platform"`
|
||||
- `title` - Optional custom title
|
||||
|
||||
See [README-technicalWriter.md](./README-technicalWriter.md) for detailed LikeC4 workflow.
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
See [TESTING.md](TESTING.md) for detailed testing documentation.
|
||||
|
||||
Quick reference:
|
||||
- `task test` - Run all tests before committing
|
||||
- `task test:quick` - Fast checks during development
|
||||
- Tests run automatically on GitHub Actions for PRs
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Hugo Configuration (`hugo.toml`)
|
||||
|
||||
Main settings:
|
||||
- `baseURL` - Site URL
|
||||
- `title` - Site title
|
||||
- `defaultContentLanguage` - Default language
|
||||
- Module imports (Docsy theme)
|
||||
|
||||
### Docsy Configuration
|
||||
|
||||
Docsy-specific settings in `hugo.toml`:
|
||||
```toml
|
||||
[params]
|
||||
github_repo = "your-repo"
|
||||
github_branch = "main"
|
||||
```
|
||||
|
||||
### Devbox Configuration (`devbox.json`)
|
||||
|
||||
Defines all development tools and their versions.
|
||||
|
||||
Update tools:
|
||||
```bash
|
||||
devbox update # Update all packages
|
||||
task deps:update # Update all dependencies (devbox + npm + hugo modules)
|
||||
```
|
||||
|
||||
## 🎨 Styling
|
||||
|
||||
Custom styles in `assets/scss/_variables_project.scss`:
|
||||
```scss
|
||||
// Override Bootstrap/Docsy variables
|
||||
$primary: #your-color;
|
||||
```
|
||||
|
||||
Hugo will process SCSS automatically with PostCSS and Autoprefixer.
|
||||
|
||||
## 🌐 Multi-Language Support
|
||||
|
||||
Add new language:
|
||||
1. Create `content/<lang>/` directory
|
||||
2. Add language config in `hugo.toml`:
|
||||
```toml
|
||||
[languages.<lang>]
|
||||
languageName = "Language Name"
|
||||
weight = 2
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### "Module not found" errors
|
||||
```bash
|
||||
hugo mod get -u
|
||||
hugo mod tidy
|
||||
```
|
||||
|
||||
### PostCSS errors
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### Build errors
|
||||
```bash
|
||||
task clean
|
||||
task build
|
||||
```
|
||||
|
||||
### Devbox issues
|
||||
```bash
|
||||
devbox update
|
||||
devbox shell --refresh
|
||||
```
|
||||
|
||||
## 📚 Resources
|
||||
|
||||
- [Hugo Documentation](https://gohugo.io/documentation/)
|
||||
- [Docsy Documentation](https://www.docsy.dev/docs/)
|
||||
- [LikeC4 Documentation](https://likec4.dev/)
|
||||
- [Taskfile Documentation](https://taskfile.dev/)
|
||||
- [Devbox Documentation](https://www.jetify.com/devbox/docs/)
|
||||
|
||||
**Project-specific guides:**
|
||||
- [README-technicalWriter.md](./README-technicalWriter.md) - Content contributor guide
|
||||
- [TESTING.md](./TESTING.md) - Detailed testing documentation
|
||||
- [DOCUMENTOR-GUIDE.md](./DOCUMENTOR-GUIDE.md) - Quick reference for technicalWriters
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
1. Create a feature branch
|
||||
2. Make your changes
|
||||
3. Run tests: `task test`
|
||||
4. Commit with semantic messages:
|
||||
- `feat(scope): add new feature`
|
||||
- `fix(scope): fix bug`
|
||||
- `docs(scope): update documentation`
|
||||
- `test(scope): add tests`
|
||||
- `chore(scope): maintenance`
|
||||
5. Push and create pull request
|
||||
|
||||
## 📦 Deployment
|
||||
|
||||
Build for production:
|
||||
```bash
|
||||
task build
|
||||
```
|
||||
|
||||
Output will be in `public/` directory, ready for deployment.
|
||||
383
doc/README-likec4.md
Normal file
383
doc/README-likec4.md
Normal file
|
|
@ -0,0 +1,383 @@
|
|||
# LikeC4 Architecture Modeling
|
||||
|
||||
This repository contains two distinct LikeC4 architecture projects for C4 model-based architecture visualization.
|
||||
|
||||
## 📁 Project Structure
|
||||
|
||||
### `resources/edp-likec4/`
|
||||
|
||||
**Enterprise Developer Platform (EDP) Architecture**
|
||||
|
||||
Contains architecture models for the platform itself - the systems, services, and infrastructure that make up the EDP.
|
||||
|
||||
- **Purpose:** Document what we build
|
||||
- **Models:** Platform components, services, deployment environments
|
||||
- **Views:** System overviews, component details, deployment diagrams
|
||||
|
||||
### `resources/doc-likec4/`
|
||||
|
||||
**Documentation Platform Architecture**
|
||||
|
||||
Contains architecture models that explain how this documentation system works - the Hugo/Docsy setup, CI/CD pipeline, and deployment process.
|
||||
|
||||
- **Purpose:** Document how we document (meta-documentation)
|
||||
- **Models:** Hugo, LikeC4, Taskfile, GitHub Actions, Edge deployment
|
||||
- **Views:** Documentation workflow, CI/CD pipeline, testing capabilities
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### 1. Install Dependencies
|
||||
|
||||
```bash
|
||||
# In the LikeC4 project directory
|
||||
cd resources/edp-likec4
|
||||
# or
|
||||
cd resources/doc-likec4
|
||||
|
||||
# Install dependencies (only once)
|
||||
npm install
|
||||
```
|
||||
|
||||
### 2. Start LikeC4 Preview
|
||||
|
||||
Preview your architecture models in the browser:
|
||||
|
||||
```bash
|
||||
npm start
|
||||
# Opens http://localhost:5173
|
||||
```
|
||||
|
||||
This launches the interactive LikeC4 viewer where you can:
|
||||
- Navigate through all views
|
||||
- Explore relationships
|
||||
- Test changes in real-time
|
||||
|
||||
### 3. Edit Models
|
||||
|
||||
Edit `.c4` files in your project:
|
||||
|
||||
**Example structure:**
|
||||
|
||||
```text
|
||||
resources/edp-likec4/
|
||||
├── models/
|
||||
│ ├── systems.c4 # System definitions
|
||||
│ ├── services.c4 # Service components
|
||||
│ └── infrastructure.c4 # Infrastructure elements
|
||||
├── views/
|
||||
│ ├── overview.c4 # High-level views
|
||||
│ ├── deployment/ # Deployment views
|
||||
│ └── components/ # Component details
|
||||
├── deployment/
|
||||
│ └── environments.c4 # Deployment configurations
|
||||
└── likec4.config.json # LikeC4 configuration
|
||||
```
|
||||
|
||||
**Example C4 model:**
|
||||
|
||||
```likec4
|
||||
specification {
|
||||
element system
|
||||
element service
|
||||
element database
|
||||
}
|
||||
|
||||
model {
|
||||
mySystem = system 'My System' {
|
||||
description 'System description'
|
||||
|
||||
backend = service 'Backend API' {
|
||||
description 'REST API service'
|
||||
}
|
||||
|
||||
db = database 'Database' {
|
||||
description 'PostgreSQL database'
|
||||
}
|
||||
|
||||
backend -> db 'reads/writes'
|
||||
}
|
||||
}
|
||||
|
||||
views {
|
||||
view systemOverview {
|
||||
title "System Overview"
|
||||
|
||||
include mySystem
|
||||
|
||||
autoLayout TopBottom
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Generate Web Components
|
||||
|
||||
After editing models, generate the web component for Hugo:
|
||||
|
||||
```bash
|
||||
# From repository root
|
||||
task likec4:generate
|
||||
```
|
||||
|
||||
This creates `static/js/likec4-webcomponent.js` (~2-3 MB) with all views.
|
||||
|
||||
### 5. Embed in Hugo
|
||||
|
||||
Use the `likec4-view` shortcode in Markdown:
|
||||
|
||||
```markdown
|
||||
{{</* likec4-view view="systemOverview" project="architecture" title="System Overview" */>}}
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `view` - View ID from your C4 model (required)
|
||||
- `project` - `"architecture"` (edp-likec4) or `"documentation-platform"` (doc-likec4)
|
||||
- `title` - Optional custom title
|
||||
|
||||
## 🔄 Development Workflow
|
||||
|
||||
### Architecture Changes Workflow
|
||||
|
||||
1. **Edit Models**
|
||||
- Modify `.c4` files in `models/` or `views/`
|
||||
|
||||
2. **Preview Changes**
|
||||
```bash
|
||||
cd resources/edp-likec4 # or doc-likec4
|
||||
npm start
|
||||
```
|
||||
Opens http://localhost:5173 for real-time preview
|
||||
|
||||
3. **Validate Models**
|
||||
```bash
|
||||
# From repository root
|
||||
task likec4:validate
|
||||
```
|
||||
|
||||
4. **Generate Web Components**
|
||||
```bash
|
||||
task likec4:generate
|
||||
```
|
||||
|
||||
5. **Test in Hugo**
|
||||
```bash
|
||||
task serve
|
||||
# Open http://localhost:1313
|
||||
```
|
||||
|
||||
6. **Commit Changes**
|
||||
```bash
|
||||
git add resources/edp-likec4/
|
||||
git add resources/doc-likec4/
|
||||
git add static/js/likec4-webcomponent.js
|
||||
git commit -m "feat: update architecture diagrams"
|
||||
```
|
||||
|
||||
### Available Tasks
|
||||
|
||||
```bash
|
||||
task likec4:generate # Generate web components from all projects
|
||||
task likec4:validate # Validate C4 models (ignore layout drift)
|
||||
task likec4:update # Update LikeC4 to latest version
|
||||
```
|
||||
|
||||
## 🔍 Finding View IDs
|
||||
|
||||
To find available view IDs for embedding:
|
||||
|
||||
```bash
|
||||
# In the project directory
|
||||
cd resources/edp-likec4
|
||||
grep -r "^view " views/ models/ --include="*.c4"
|
||||
|
||||
# Or search all C4 files
|
||||
grep -r "view\s\+\w" . --include="*.c4"
|
||||
```
|
||||
|
||||
View IDs are defined in your C4 files:
|
||||
|
||||
```likec4
|
||||
views {
|
||||
view myViewId { # ← This is the view ID
|
||||
title "My View"
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 📚 LikeC4 Syntax
|
||||
|
||||
### Specification Block
|
||||
|
||||
Define element and relationship types:
|
||||
|
||||
```likec4
|
||||
specification {
|
||||
element person
|
||||
element system
|
||||
element container
|
||||
element component
|
||||
|
||||
relationship async
|
||||
relationship sync
|
||||
}
|
||||
```
|
||||
|
||||
### Model Block
|
||||
|
||||
Define your architecture:
|
||||
|
||||
```likec4
|
||||
model {
|
||||
customer = person 'Customer' {
|
||||
description 'End user'
|
||||
}
|
||||
|
||||
system = system 'My System' {
|
||||
frontend = container 'Frontend' {
|
||||
description 'React application'
|
||||
}
|
||||
|
||||
backend = container 'Backend' {
|
||||
description 'Node.js API'
|
||||
}
|
||||
|
||||
frontend -> backend 'API calls'
|
||||
}
|
||||
|
||||
customer -> system.frontend 'uses'
|
||||
}
|
||||
```
|
||||
|
||||
### Views Block
|
||||
|
||||
Create diagrams:
|
||||
|
||||
```likec4
|
||||
views {
|
||||
view overview {
|
||||
title "System Overview"
|
||||
|
||||
include *
|
||||
|
||||
autoLayout TopBottom
|
||||
}
|
||||
|
||||
view systemDetail {
|
||||
title "System Details"
|
||||
|
||||
include system.*
|
||||
|
||||
autoLayout LeftRight
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🎯 Common View IDs
|
||||
|
||||
### EDP Platform (resources/edp-likec4/)
|
||||
|
||||
- `edp` - EDP overview
|
||||
- `landscape` - Developer landscape
|
||||
- `otc-faas` - OTC FaaS deployment
|
||||
- `edpbuilderworkflow` - Builder workflow
|
||||
- Component views: `keycloak`, `forgejo`, `argoCD`, etc.
|
||||
|
||||
### Documentation Platform (resources/doc-likec4/)
|
||||
|
||||
- `overview` - Complete system overview
|
||||
- `localDevelopment` - Technical Writer workflow
|
||||
- `cicdPipeline` - CI/CD pipeline
|
||||
- `deploymentFlow` - Edge deployment
|
||||
- `fullWorkflow` - End-to-end workflow
|
||||
- `testingCapabilities` - Testing overview
|
||||
|
||||
## 🛠️ Configuration
|
||||
|
||||
### likec4.config.json
|
||||
|
||||
Each project has a configuration file:
|
||||
|
||||
```json
|
||||
{
|
||||
"sources": [
|
||||
"models/**/*.c4",
|
||||
"views/**/*.c4",
|
||||
"deployment/**/*.c4"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
This tells LikeC4 where to find your model files.
|
||||
|
||||
## 🔗 Integration with Hugo
|
||||
|
||||
### How It Works
|
||||
|
||||
1. **Source:** `.c4` files contain your architecture models
|
||||
2. **Codegen:** `task likec4:generate` creates a self-contained web component
|
||||
3. **Static Asset:** `static/js/likec4-webcomponent.js` bundled with Hugo site
|
||||
4. **Custom Element:** Web Components standard enables `<likec4-view>` tag
|
||||
5. **Rendering:** Shadow DOM renders interactive diagrams
|
||||
|
||||
### Web Component Registration
|
||||
|
||||
The web component is automatically loaded via `layouts/partials/hooks/head-end.html`:
|
||||
|
||||
```html
|
||||
<script type="module" src="/js/likec4-loader.js"></script>
|
||||
```
|
||||
|
||||
This loader dynamically loads the LikeC4 web component only on pages that use it.
|
||||
|
||||
### Styling
|
||||
|
||||
Custom styles in `static/css/likec4-styles.css`:
|
||||
- Dark mode support
|
||||
- Telekom magenta color scheme
|
||||
- Responsive sizing
|
||||
- Loading indicators
|
||||
|
||||
## 📖 Resources
|
||||
|
||||
- [LikeC4 Documentation](https://likec4.dev/)
|
||||
- [LikeC4 GitHub](https://github.com/likec4/likec4)
|
||||
- [C4 Model](https://c4model.com/)
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Web Component Not Rendering
|
||||
|
||||
1. Check that view ID exists:
|
||||
```bash
|
||||
grep -r "view yourViewId" resources/
|
||||
```
|
||||
|
||||
2. Regenerate web component:
|
||||
```bash
|
||||
task likec4:generate
|
||||
```
|
||||
|
||||
3. Clear browser cache and reload
|
||||
|
||||
### Layout Drift Warnings
|
||||
|
||||
Layout drift warnings during validation are expected and can be ignored:
|
||||
|
||||
```bash
|
||||
task likec4:validate # Ignores layout drift
|
||||
task likec4:validate:layout # Full validation including layout
|
||||
```
|
||||
|
||||
### NPM Errors
|
||||
|
||||
```bash
|
||||
cd resources/edp-likec4
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
## 🎓 Learn More
|
||||
|
||||
For detailed usage in content creation, see:
|
||||
- [README-technicalWriter.md](./README-technicalWriter.md) - Content contributor guide
|
||||
- [content/en/docs/documentation/local-development.md](./content/en/docs/documentation/local-development.md) - Local development guide
|
||||
434
doc/README-technical-writer.md
Normal file
434
doc/README-technical-writer.md
Normal file
|
|
@ -0,0 +1,434 @@
|
|||
# Technical Writer Guide
|
||||
|
||||
Welcome! This guide helps you contribute to the IPCEI-CIS Developer Framework documentation.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Basic knowledge of Markdown
|
||||
- Git installed
|
||||
- Either **Devbox** (recommended) or manual tool installation
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Clone and Setup
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone <repository-url>
|
||||
cd ipceicis-developerframework
|
||||
|
||||
# Install dependencies
|
||||
task deps:install
|
||||
|
||||
# If using Devbox
|
||||
devbox shell
|
||||
```
|
||||
|
||||
### 2. Start Development Server
|
||||
|
||||
```bash
|
||||
task serve
|
||||
```
|
||||
|
||||
Open your browser at `http://localhost:1313` - changes appear instantly!
|
||||
|
||||
### 3. Create Content
|
||||
|
||||
Create a new page:
|
||||
|
||||
```bash
|
||||
# Example: Add a new guide
|
||||
vim content/en/docs/your-topic/_index.md
|
||||
```
|
||||
|
||||
Add frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Your Topic"
|
||||
linkTitle: "Your Topic"
|
||||
weight: 10
|
||||
description: >
|
||||
Brief description of your topic.
|
||||
---
|
||||
|
||||
Your content here...
|
||||
```
|
||||
|
||||
### 4. Test and Commit
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
task test:quick
|
||||
|
||||
# Commit your changes
|
||||
git add .
|
||||
git commit -m "docs: Add guide for X"
|
||||
git push
|
||||
```
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
```
|
||||
content/en/
|
||||
├── _index.md # Homepage
|
||||
├── docs/
|
||||
│ ├── architecture/ # Architecture documentation
|
||||
│ │ └── highlevelarch.md
|
||||
│ ├── documentation/ # Documentation guides
|
||||
│ │ ├── local-development.md
|
||||
│ │ ├── testing.md
|
||||
│ │ └── cicd.md
|
||||
│ ├── decisions/ # ADRs (Architecture Decision Records)
|
||||
│ └── v1/ # Legacy documentation
|
||||
└── blog/ # Blog posts
|
||||
└── 20250401_review.md
|
||||
```
|
||||
|
||||
## Writing Documentation
|
||||
|
||||
### Markdown Basics
|
||||
|
||||
```markdown
|
||||
# Heading 1
|
||||
## Heading 2
|
||||
### Heading 3
|
||||
|
||||
**Bold text**
|
||||
*Italic text*
|
||||
|
||||
- Bullet list
|
||||
- Item 2
|
||||
|
||||
1. Numbered list
|
||||
2. Item 2
|
||||
|
||||
[Link text](https://example.com)
|
||||
|
||||
`inline code`
|
||||
|
||||
\`\`\`bash
|
||||
# Code block
|
||||
echo "Hello"
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Using Shortcodes
|
||||
|
||||
#### Alerts
|
||||
|
||||
```markdown
|
||||
{{< alert title="Note" >}}
|
||||
Important information here
|
||||
{{< /alert >}}
|
||||
|
||||
{{< alert title="Warning" color="warning" >}}
|
||||
Warning message
|
||||
{{< /alert >}}
|
||||
```
|
||||
|
||||
#### Code Tabs
|
||||
|
||||
```markdown
|
||||
{{< tabpane >}}
|
||||
{{< tab header="Bash" >}}
|
||||
\`\`\`bash
|
||||
echo "Hello"
|
||||
\`\`\`
|
||||
{{< /tab >}}
|
||||
{{< tab header="Python" >}}
|
||||
\`\`\`python
|
||||
print("Hello")
|
||||
\`\`\`
|
||||
{{< /tab >}}
|
||||
{{< /tabpane >}}
|
||||
```
|
||||
|
||||
## Creating Architecture Diagrams
|
||||
|
||||
### 1. Edit LikeC4 Models
|
||||
|
||||
Navigate to the appropriate project:
|
||||
- `resources/edp-likec4/` - Platform architecture
|
||||
- `resources/doc-likec4/` - Documentation platform architecture
|
||||
|
||||
Create or edit `.c4` files:
|
||||
|
||||
```likec4
|
||||
specification {
|
||||
element person
|
||||
element system
|
||||
}
|
||||
|
||||
model {
|
||||
user = person 'User' {
|
||||
description 'End user of the platform'
|
||||
}
|
||||
|
||||
platform = system 'Platform' {
|
||||
description 'The EDP platform'
|
||||
}
|
||||
|
||||
user -> platform 'uses'
|
||||
}
|
||||
|
||||
views {
|
||||
view overview {
|
||||
title "System Overview"
|
||||
|
||||
include user
|
||||
include platform
|
||||
|
||||
autoLayout TopBottom
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Generate Webcomponent
|
||||
|
||||
```bash
|
||||
task likec4:generate
|
||||
```
|
||||
|
||||
### 3. Embed in Documentation
|
||||
|
||||
```markdown
|
||||
{{< likec4-view view="overview" project="architecture" title="System Overview" >}}
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `view` - View ID from your `.c4` file
|
||||
- `project` - `"architecture"` or `"documentation-platform"`
|
||||
- `title` - Custom header text (optional)
|
||||
|
||||
### 4. Find Available Views
|
||||
|
||||
```bash
|
||||
# List all view IDs
|
||||
grep -r "^view " resources/edp-likec4/ --include="*.c4"
|
||||
```
|
||||
|
||||
## Available Tasks
|
||||
|
||||
View all tasks:
|
||||
|
||||
```bash
|
||||
task --list
|
||||
```
|
||||
|
||||
### Development Tasks
|
||||
|
||||
| Task | Description |
|
||||
|------|-------------|
|
||||
| `task serve` | Start dev server with hot reload |
|
||||
| `task build` | Build production site |
|
||||
| `task clean` | Remove build artifacts |
|
||||
| `task test` | Run all tests (build, markdown, HTML, links) |
|
||||
| `task test:quick` | Run quick tests (build, markdown) |
|
||||
|
||||
### LikeC4 Tasks
|
||||
|
||||
| Task | Description |
|
||||
|------|-------------|
|
||||
| `task likec4:generate` | Generate webcomponents from `.c4` files |
|
||||
| `task likec4:validate` | Validate LikeC4 syntax |
|
||||
| `task likec4:update` | Update LikeC4 to latest version |
|
||||
|
||||
### Dependency Tasks
|
||||
|
||||
| Task | Description |
|
||||
|------|-------------|
|
||||
| `task deps:install` | Install all dependencies |
|
||||
| `task deps:update` | Update dependencies |
|
||||
|
||||
## Testing
|
||||
|
||||
### Quick Test (Recommended)
|
||||
|
||||
Before committing:
|
||||
|
||||
```bash
|
||||
task test:quick
|
||||
```
|
||||
|
||||
Validates:
|
||||
- Hugo build succeeds
|
||||
- Markdown syntax is correct
|
||||
- LikeC4 models are valid
|
||||
|
||||
### Full Test
|
||||
|
||||
Includes link checking:
|
||||
|
||||
```bash
|
||||
task test
|
||||
```
|
||||
|
||||
**Note:** Link checking can be slow. Use `test:quick` during development.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Writing Style
|
||||
|
||||
✅ **Do:**
|
||||
- Write in present tense: "The system processes..."
|
||||
- Use code blocks with syntax highlighting
|
||||
- Keep sections concise (3-5 paragraphs max)
|
||||
- Add diagrams for complex concepts
|
||||
- Use bullet points for lists
|
||||
- Test locally before committing
|
||||
|
||||
❌ **Don't:**
|
||||
- Use future tense: "The system will process..."
|
||||
- Write long paragraphs (split into sections)
|
||||
- Forget to add descriptions in frontmatter
|
||||
- Commit without testing
|
||||
|
||||
### Frontmatter
|
||||
|
||||
Always include:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Page Title" # Full title
|
||||
linkTitle: "Short Title" # Used in navigation
|
||||
weight: 10 # Order in menu (lower = higher)
|
||||
description: > # Used in SEO and cards
|
||||
Brief description of the page content.
|
||||
---
|
||||
```
|
||||
|
||||
Optional:
|
||||
|
||||
```yaml
|
||||
---
|
||||
date: 2025-01-15 # Publication date (for blog posts)
|
||||
author: "Your Name" # Author name
|
||||
categories: ["Category"] # Categories
|
||||
tags: ["tag1", "tag2"] # Tags
|
||||
---
|
||||
```
|
||||
|
||||
### File Naming
|
||||
|
||||
- Use lowercase
|
||||
- Use hyphens, not underscores: `my-guide.md` not `my_guide.md`
|
||||
- Main page in a section: `_index.md`
|
||||
- Single page: `page-name.md`
|
||||
|
||||
### Images
|
||||
|
||||
Place images in the same folder as your markdown file:
|
||||
|
||||
```
|
||||
docs/my-guide/
|
||||
├── _index.md
|
||||
├── screenshot.png
|
||||
└── diagram.svg
|
||||
```
|
||||
|
||||
Reference them:
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Port 1313 already in use
|
||||
|
||||
```bash
|
||||
# Find and kill the process
|
||||
lsof -ti:1313 | xargs kill -9
|
||||
```
|
||||
|
||||
### Build errors
|
||||
|
||||
```bash
|
||||
# Clean and rebuild
|
||||
task clean
|
||||
task build:dev
|
||||
```
|
||||
|
||||
### Hugo not found (when not using Devbox)
|
||||
|
||||
```bash
|
||||
# Make sure you're in devbox shell
|
||||
devbox shell
|
||||
|
||||
# Or install Hugo manually
|
||||
# See: https://gohugo.io/installation/
|
||||
```
|
||||
|
||||
### LikeC4 validation fails
|
||||
|
||||
```bash
|
||||
# Validate with detailed output
|
||||
cd resources/edp-likec4
|
||||
npx likec4 validate --verbose
|
||||
|
||||
# Ignore layout drift (common, not critical)
|
||||
npx likec4 validate --ignore-layout
|
||||
```
|
||||
|
||||
## Git Workflow
|
||||
|
||||
### Create a Branch
|
||||
|
||||
```bash
|
||||
git checkout -b feature/my-new-guide
|
||||
```
|
||||
|
||||
### Commit Changes
|
||||
|
||||
```bash
|
||||
# Stage your changes
|
||||
git add content/en/docs/my-guide/
|
||||
|
||||
# Commit with clear message
|
||||
git commit -m "docs: Add guide for X feature"
|
||||
```
|
||||
|
||||
### Commit Message Convention
|
||||
|
||||
Format: `<type>: <description>`
|
||||
|
||||
Types:
|
||||
- `docs:` - Documentation changes
|
||||
- `feat:` - New feature or content
|
||||
- `fix:` - Bug fix or correction
|
||||
- `chore:` - Maintenance tasks
|
||||
- `style:` - CSS/styling changes
|
||||
|
||||
Examples:
|
||||
```
|
||||
docs: Add installation guide for Windows users
|
||||
feat: Add interactive architecture diagram for OTC deployment
|
||||
fix: Correct typo in API documentation
|
||||
chore: Update LikeC4 to version 1.43.0
|
||||
```
|
||||
|
||||
### Push and Create PR
|
||||
|
||||
```bash
|
||||
# Push your branch
|
||||
git push origin feature/my-new-guide
|
||||
|
||||
# Create Pull Request on Forgejo/GitHub
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Full Documentation**: See `/content/en/docs/documentation/`
|
||||
- **LikeC4 Documentation**: https://likec4.dev/
|
||||
- **Hugo Documentation**: https://gohugo.io/documentation/
|
||||
- **Docsy Theme**: https://www.docsy.dev/docs/
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Read the [Local Development Guide](./content/en/docs/documentation/local-development.md)
|
||||
2. Explore [Architecture Documentation](./content/en/docs/architecture/)
|
||||
3. Check [Testing Guide](./content/en/docs/documentation/testing.md)
|
||||
4. Learn about [CI/CD Pipeline](./content/en/docs/documentation/cicd.md)
|
||||
|
||||
Happy documenting! 📝✨
|
||||
207
doc/RELEASE.md
Normal file
207
doc/RELEASE.md
Normal file
|
|
@ -0,0 +1,207 @@
|
|||
# Release Process
|
||||
|
||||
This document describes the release process for the IPCEI-CIS Developer Framework.
|
||||
|
||||
## Overview
|
||||
|
||||
The project uses **Semantic Versioning** (SemVer) for releases. Each release is triggered by a Git tag and automatically creates:
|
||||
|
||||
- Multi-platform Docker images (linux/amd64, linux/arm64)
|
||||
- Forgejo release with release notes
|
||||
- Automatically generated changelog
|
||||
|
||||
## Versioning Schema
|
||||
|
||||
We follow [Semantic Versioning 2.0.0](https://semver.org/):
|
||||
|
||||
- `MAJOR.MINOR.PATCH` (e.g., `v1.2.3`)
|
||||
- **MAJOR**: Breaking changes (incompatible API changes)
|
||||
- **MINOR**: New features (backwards compatible)
|
||||
- **PATCH**: Bug fixes (backwards compatible)
|
||||
|
||||
## Creating a Release
|
||||
|
||||
### 1. Check Prerequisites
|
||||
|
||||
Ensure that:
|
||||
|
||||
- All tests are passing (`task test`)
|
||||
- CI pipeline runs successfully
|
||||
- All desired changes are in the `main` branch
|
||||
- You have the latest version: `git pull origin main`
|
||||
|
||||
### 2. Determine Version
|
||||
|
||||
Determine the new version number based on the changes:
|
||||
|
||||
```bash
|
||||
# Show current tag
|
||||
git describe --tags --abbrev=0
|
||||
|
||||
# Show commits since last release
|
||||
git log $(git describe --tags --abbrev=0)..HEAD --oneline
|
||||
```
|
||||
|
||||
### 3. Create Tag
|
||||
|
||||
Create an annotated tag with the new version:
|
||||
|
||||
```bash
|
||||
# For a new patch release (e.g., v1.2.3 → v1.2.4)
|
||||
git tag -a v1.2.4 -m "Release v1.2.4"
|
||||
|
||||
# For a minor release (e.g., v1.2.3 → v1.3.0)
|
||||
git tag -a v1.3.0 -m "Release v1.3.0"
|
||||
|
||||
# For a major release (e.g., v1.2.3 → v2.0.0)
|
||||
git tag -a v2.0.0 -m "Release v2.0.0"
|
||||
```
|
||||
|
||||
### 4. Push Tag
|
||||
|
||||
Push the tag to the repository - this triggers the release pipeline:
|
||||
|
||||
```bash
|
||||
git push origin v1.2.4
|
||||
```
|
||||
|
||||
### 5. Monitor Release Pipeline
|
||||
|
||||
The release pipeline (`release.yaml`) starts automatically:
|
||||
|
||||
1. Open the Actions tab in Forgejo
|
||||
2. Monitor the `release` workflow
|
||||
3. On success: Release is visible on the Releases page
|
||||
|
||||
## What Happens Automatically?
|
||||
|
||||
The release pipeline (`release.yaml`) performs the following steps:
|
||||
|
||||
1. **Build Docker Images**
|
||||
- Multi-platform build (AMD64 + ARM64)
|
||||
- Images are tagged with:
|
||||
- `vX.Y.Z` (exact version, e.g., `v1.2.3`)
|
||||
- `vX.Y` (minor version, e.g., `v1.2`)
|
||||
- `vX` (major version, e.g., `v1`)
|
||||
- `latest` (latest release)
|
||||
|
||||
2. **Push Images**
|
||||
- To the container registry (Forgejo Packages)
|
||||
|
||||
3. **Generate Changelog**
|
||||
- Automatically from Git commits since last release
|
||||
- Format: `- Commit Message (hash)`
|
||||
|
||||
4. **Create Forgejo Release**
|
||||
- With generated release notes
|
||||
- Contains build versions (Node, Go, Hugo)
|
||||
- Docker pull commands
|
||||
- Changelog
|
||||
|
||||
## Using Docker Images
|
||||
|
||||
After a successful release, the images are available:
|
||||
|
||||
```bash
|
||||
# Specific version
|
||||
docker pull <registry>/<repository>:v1.2.3
|
||||
|
||||
# Latest
|
||||
docker pull <registry>/<repository>:latest
|
||||
|
||||
# Major/Minor version
|
||||
docker pull <registry>/<repository>:v1
|
||||
docker pull <registry>/<repository>:v1.2
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Commit Messages
|
||||
|
||||
Use meaningful commit messages, as they will appear in the changelog:
|
||||
|
||||
```bash
|
||||
# Good
|
||||
git commit -m "fix: correct multi-platform Docker build for ARM64"
|
||||
git commit -m "feat: add automatic release pipeline"
|
||||
git commit -m "docs: update RELEASE.md"
|
||||
|
||||
# Bad
|
||||
git commit -m "fix stuff"
|
||||
git commit -m "wip"
|
||||
```
|
||||
|
||||
**Conventional Commits** help with categorization:
|
||||
|
||||
- `feat:` - New features
|
||||
- `fix:` - Bug fixes
|
||||
- `docs:` - Documentation
|
||||
- `chore:` - Maintenance
|
||||
- `refactor:` - Code restructuring
|
||||
- `test:` - Tests
|
||||
|
||||
### Release Frequency
|
||||
|
||||
- **Patch releases**: As needed (bug fixes)
|
||||
- **Minor releases**: Regular (new features)
|
||||
- **Major releases**: Rare (breaking changes)
|
||||
|
||||
### Hotfixes
|
||||
|
||||
For urgent bug fixes:
|
||||
|
||||
1. Create branch from last release tag
|
||||
2. Fix the bug
|
||||
3. Create new patch release
|
||||
|
||||
```bash
|
||||
git checkout v1.2.3
|
||||
git checkout -b hotfix/critical-bug
|
||||
# Implement fix
|
||||
git commit -m "fix: critical bugfix"
|
||||
git tag -a v1.2.4 -m "Release v1.2.4 - Hotfix"
|
||||
git push origin v1.2.4
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Release Pipeline Fails
|
||||
|
||||
1. **Check Secrets**: `PACKAGES_USER`, `PACKAGES_TOKEN` must be set
|
||||
2. **Check Logs**: Open the failed workflow in the Actions tab
|
||||
3. **Local Test**:
|
||||
|
||||
```bash
|
||||
task build:oci-image
|
||||
task test:oci-image
|
||||
```
|
||||
|
||||
### Delete/Correct Tag
|
||||
|
||||
**Locally:**
|
||||
|
||||
```bash
|
||||
git tag -d v1.2.3
|
||||
```
|
||||
|
||||
**Remote:**
|
||||
|
||||
```bash
|
||||
git push --delete origin v1.2.3
|
||||
```
|
||||
|
||||
⚠️ **Warning**: Releases should not be deleted after they have been published!
|
||||
|
||||
### Edit Release Notes Afterwards
|
||||
|
||||
Release notes can be manually edited in Forgejo:
|
||||
|
||||
1. Go to Releases
|
||||
2. Click on the release
|
||||
3. Click "Edit"
|
||||
|
||||
## Further Information
|
||||
|
||||
- [Semantic Versioning](https://semver.org/)
|
||||
- [Conventional Commits](https://www.conventionalcommits.org/)
|
||||
- [Keep a Changelog](https://keepachangelog.com/)
|
||||
4
doc/TODO.md
Normal file
4
doc/TODO.md
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
# Todos
|
||||
|
||||
[] update and rework READMEs, reduce likec4 description
|
||||
[] remove / consolidate doc-likec4 with edp-likec4 (as it seems that webcomponents only work for one likec4-config)
|
||||
Loading…
Add table
Add a link
Reference in a new issue