Skip to content

Commit 9ceed9a

Browse files
BregorBregor
committed
Build System: PostCSS migration
**Changed** - **Build System**: Migrated to PostCSS-based modular architecture - Source files now organized in `src/modules/` directory - Build process uses `postcss-import`, `postcss-nesting`, and `autoprefixer` - Enables better code organization and maintainability - Developers should use `npm run build` or `npm run watch` for development **Added** - **CI/CD Pipeline**: GitHub Actions workflows for automated building and releases - Build validation on every push/PR - Automatic release creation when version tags are pushed - Built CSS distributed via GitHub Releases, not committed to repository - **Release Script**: `npm run prepare-release` for streamlined version management - **Documentation**: Comprehensive guides for build system and release process **Technical** - Source code split into focused modules: `_vars.css`, `_containers.css`, `preview.css`, `source.css`, `mobile.css`, `a11y.css`, `print.css`, `debug.css` - PostCSS nesting support for cleaner source code - Source maps generated for easier debugging (not included in distribution) - Built CSS removed from git tracking (`.gitignore`) - GitHub Actions workflows: `build.yml` and `release.yml` - Updated all documentation to reflect CI/CD workflow
1 parent 706e590 commit 9ceed9a

20 files changed

Lines changed: 2547 additions & 35 deletions

‎.github/RELEASE_WORKFLOW.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# Release Workflow Guide
2+
3+
This document explains the CI/CD setup and release process for Variable Content Width.
4+
5+
## Overview
6+
7+
The project uses GitHub Actions to automatically build and distribute the CSS snippet. This ensures:
8+
- Clean git history (no built files committed)
9+
- Reproducible builds (consistent environment)
10+
- Automated releases (one command to publish)
11+
- Build validation on every PR
12+
13+
## Architecture
14+
15+
### Source Code (Git)
16+
```
17+
src/
18+
├── variable-content-width.css # Entry point
19+
└── modules/
20+
├── _vars.css # Variables
21+
├── _containers.css # Container queries
22+
├── preview.css # Preview mode
23+
├── source.css # Source mode
24+
├── mobile.css # Mobile styles
25+
├── a11y.css # Accessibility
26+
├── print.css # Print styles
27+
└── debug.css # Debug mode
28+
```
29+
30+
### Built Output (NOT in Git)
31+
```
32+
variable-content-width.css # Built, distributed via releases
33+
variable-content-width.css.map # Source maps (dev only)
34+
```
35+
36+
### CI/CD Workflows
37+
38+
#### 1. Build Workflow (`build.yml`)
39+
**Triggers**: Every push/PR to main or version branches
40+
41+
**Purpose**: Validate that code builds successfully
42+
43+
**Steps**:
44+
1. Checkout code
45+
2. Install dependencies (`npm ci`)
46+
3. Build CSS (`npm run build`)
47+
4. Verify output exists
48+
5. Upload artifact (available for 30 days)
49+
50+
**Result**: Green checkmark on PRs means code will build successfully
51+
52+
#### 2. Release Workflow (`release.yml`)
53+
**Triggers**: When a version tag is pushed (e.g., `v0.2.0`)
54+
55+
**Purpose**: Automatically create releases with built CSS
56+
57+
**Steps**:
58+
1. Checkout code
59+
2. Install dependencies
60+
3. Build CSS from source
61+
4. Create GitHub release with the tag
62+
5. Attach built CSS as downloadable asset
63+
6. Auto-generate release notes
64+
65+
**Result**: Users can download `variable-content-width.css` from the release page
66+
67+
## Creating a Release
68+
69+
### Method 1: Using the Prepare Script (Recommended)
70+
71+
```bash
72+
npm run prepare-release
73+
```
74+
75+
This interactive script will:
76+
1. Check for uncommitted changes
77+
2. Prompt for version bump type
78+
3. Update `package.json`
79+
4. Build CSS to verify it works
80+
5. Remind you to update `CHANGELOG.md`
81+
6. Provide exact commands to complete the release
82+
83+
### Method 2: Manual Steps
84+
85+
1. **Update version in package.json**
86+
```bash
87+
npm version patch # or minor, or major
88+
# This creates: 0.2.0 → 0.2.1 (patch)
89+
# 0.2.0 → 0.3.0 (minor)
90+
# 0.2.0 → 1.0.0 (major)
91+
```
92+
93+
2. **Update CHANGELOG.md**
94+
- Change `## [0.2.0] - TBD` to `## [0.2.0] - 2025-10-05`
95+
- Add release notes under appropriate sections
96+
97+
3. **Test the build locally**
98+
```bash
99+
npm run build
100+
# Verify it builds without errors
101+
# Built file will be ignored by git
102+
```
103+
104+
4. **Commit changes**
105+
```bash
106+
git add package.json CHANGELOG.md
107+
git commit -m "Release v0.2.0"
108+
git push origin main
109+
```
110+
111+
5. **Create and push the version tag**
112+
```bash
113+
git tag v0.2.0
114+
git push origin v0.2.0
115+
```
116+
117+
6. **Wait for GitHub Actions**
118+
- Go to: https://github.com/Bregor/obsidian-variable-content-width/actions
119+
- Watch the "Release" workflow run
120+
- Should complete in ~1-2 minutes
121+
122+
7. **Verify the release**
123+
- Go to: https://github.com/Bregor/obsidian-variable-content-width/releases
124+
- Verify the release was created
125+
- Verify `variable-content-width.css` is attached
126+
- Test downloading and using it in Obsidian
127+
128+
## Versioning Strategy
129+
130+
Follow [Semantic Versioning](https://semver.org/):
131+
132+
- **Patch** (0.2.0 → 0.2.1): Bug fixes, no new features
133+
- **Minor** (0.2.0 → 0.3.0): New features, backward compatible
134+
- **Major** (0.2.0 → 1.0.0): Breaking changes
135+
136+
## Distribution Model
137+
138+
### For Users
139+
1. Go to [Releases](https://github.com/Bregor/obsidian-variable-content-width/releases)
140+
2. Download `variable-content-width.css` from latest release
141+
3. Install in Obsidian snippets folder
142+
143+
### For Contributors
144+
1. Clone repository
145+
2. Edit source files in `src/`
146+
3. Run `npm run watch` for live rebuilding
147+
4. Submit PR (built file is NOT included)
148+
5. CI validates the build automatically
149+
150+
## Troubleshooting
151+
152+
### Build fails in CI
153+
- Run `npm run build` locally to see the error
154+
- Fix the issue in source files
155+
- Commit and push the fix
156+
157+
### Release workflow doesn't trigger
158+
- Ensure you pushed the tag: `git push origin v0.2.0`
159+
- Check that tag format matches `v*` pattern
160+
- Verify workflows are enabled in repository settings
161+
162+
### Release created but no CSS attached
163+
- Check workflow logs for build errors
164+
- Verify `variable-content-width.css` is created during build
165+
- Check file path in `release.yml` is correct
166+
167+
### Want to delete a bad release
168+
```bash
169+
# Delete the tag locally
170+
git tag -d v0.2.0
171+
172+
# Delete the tag remotely
173+
git push origin :refs/tags/v0.2.0
174+
175+
# Delete the release on GitHub (use web UI)
176+
```
177+
178+
Then fix the issue and create a new release with a bumped version.
179+
180+
## Best Practices
181+
182+
1. **Always test locally before tagging**
183+
```bash
184+
npm run build
185+
# Test the built CSS in Obsidian
186+
```
187+
188+
2. **Update CHANGELOG.md before releasing**
189+
- Users read this to understand changes
190+
- Include migration notes for breaking changes
191+
192+
3. **Use meaningful commit messages**
193+
- CI logs will reference these
194+
- Helps with debugging failed releases
195+
196+
4. **One release at a time**
197+
- Don't create multiple tags simultaneously
198+
- Wait for previous release workflow to complete
199+
200+
5. **Monitor the Actions tab**
201+
- Watch for build failures
202+
- Address issues quickly
203+
204+
## Future Enhancements
205+
206+
Potential improvements to consider:
207+
208+
- [ ] Automated changelog generation from commits
209+
- [ ] Pre-release/beta distribution via branches
210+
- [ ] CSS minification for smaller file size
211+
- [ ] Automated testing of CSS validity
212+
- [ ] Version bump suggestions based on commit messages
213+
- [ ] Slack/Discord notifications on releases

‎.github/workflows/build.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Build and Test
2+
3+
on:
4+
push:
5+
branches: [ main, v* ]
6+
pull_request:
7+
branches: [ main, v* ]
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- name: Checkout repository
15+
uses: actions/checkout@v4
16+
17+
- name: Setup Node.js
18+
uses: actions/setup-node@v4
19+
with:
20+
node-version: '20'
21+
cache: 'npm'
22+
23+
- name: Install dependencies
24+
run: npm ci
25+
26+
- name: Build CSS
27+
run: npm run build
28+
29+
- name: Check build output exists
30+
run: |
31+
if [ ! -f variable-content-width.css ]; then
32+
echo "Error: Built CSS file not found"
33+
exit 1
34+
fi
35+
echo "Build successful, file size: $(wc -c < variable-content-width.css) bytes"
36+
37+
- name: Upload build artifact
38+
uses: actions/upload-artifact@v4
39+
with:
40+
name: css-build
41+
path: variable-content-width.css
42+
retention-days: 30

‎.github/workflows/release.yml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
8+
permissions:
9+
contents: write
10+
11+
jobs:
12+
release:
13+
runs-on: ubuntu-latest
14+
15+
steps:
16+
- name: Checkout repository
17+
uses: actions/checkout@v4
18+
19+
- name: Setup Node.js
20+
uses: actions/setup-node@v4
21+
with:
22+
node-version: '20'
23+
cache: 'npm'
24+
25+
- name: Install dependencies
26+
run: npm ci
27+
28+
- name: Build CSS
29+
run: npm run build
30+
31+
- name: Verify build
32+
run: |
33+
if [ ! -f variable-content-width.css ]; then
34+
echo "Error: Built CSS file not found"
35+
exit 1
36+
fi
37+
SIZE=$(wc -c < variable-content-width.css)
38+
echo "Build successful, file size: $SIZE bytes"
39+
40+
- name: Extract version from tag
41+
id: get_version
42+
run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
43+
44+
- name: Create Release
45+
uses: softprops/action-gh-release@v1
46+
with:
47+
files: |
48+
variable-content-width.css
49+
body: |
50+
## Installation
51+
52+
Download `variable-content-width.css` and place it in your Obsidian snippets folder:
53+
1. Open Obsidian Settings → Appearance → CSS Snippets
54+
2. Click the folder icon to open snippets folder
55+
3. Place `variable-content-width.css` in the folder
56+
4. Refresh the snippets list and enable "Variable Content Width"
57+
58+
See [README.md](https://github.com/${{ github.repository }}/blob/${{ github.ref_name }}/README.md) for full documentation.
59+
60+
## What's Changed
61+
See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/${{ github.ref_name }}/CHANGELOG.md) for details.
62+
draft: false
63+
prerelease: false
64+
env:
65+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Dependencies
2+
node_modules
3+
4+
# Build output (distributed via GitHub releases)
5+
variable-content-width.css
6+
*.map

‎CHANGELOG.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,31 @@ All notable changes to the Variable Content Width snippet will be documented in
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## [0.2.0] - TBD
9+
10+
### Changed
11+
- **Build System**: Migrated to PostCSS-based modular architecture
12+
- Source files now organized in `src/modules/` directory
13+
- Build process uses `postcss-import`, `postcss-nesting`, and `autoprefixer`
14+
- Enables better code organization and maintainability
15+
- Developers should use `npm run build` or `npm run watch` for development
16+
17+
### Added
18+
- **CI/CD Pipeline**: GitHub Actions workflows for automated building and releases
19+
- Build validation on every push/PR
20+
- Automatic release creation when version tags are pushed
21+
- Built CSS distributed via GitHub Releases, not committed to repository
22+
- **Release Script**: `npm run prepare-release` for streamlined version management
23+
- **Documentation**: Comprehensive guides for build system and release process
24+
25+
### Technical
26+
- Source code split into focused modules: `_vars.css`, `_containers.css`, `preview.css`, `source.css`, `mobile.css`, `a11y.css`, `print.css`, `debug.css`
27+
- PostCSS nesting support for cleaner source code
28+
- Source maps generated for easier debugging (not included in distribution)
29+
- Built CSS removed from git tracking (`.gitignore`)
30+
- GitHub Actions workflows: `build.yml` and `release.yml`
31+
- Updated all documentation to reflect CI/CD workflow
32+
833
## [0.1.0] - 2025-09-28
934

1035
### Added

0 commit comments

Comments
 (0)