Skip to content

Commit 21454a0

Browse files
Update deployment documentation and add gh-pages cleanup script to align with DevOps Visions standards
1 parent 79c2d58 commit 21454a0

5 files changed

Lines changed: 228 additions & 22 deletions

File tree

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# GitHub Pages Clean Structure Guide
2+
3+
This guide outlines the proper structure for the GitHub Pages (gh-pages) branch following DevOps Visions standards.
4+
5+
## Purpose
6+
7+
The `gh-pages` branch serves one specific purpose:
8+
- Host the built version of our website for GitHub Pages
9+
10+
It should **not** be used for:
11+
- Development work
12+
- Source code storage
13+
- Documentation beyond what's needed for the deployed site
14+
15+
## Standard Structure
16+
17+
The following represents the proper structure for the `gh-pages` branch:
18+
19+
```
20+
elmentor-landing-page-clean/
21+
├── assets/ # Compiled JS/CSS and other assets
22+
├── index.html # Main HTML file (built)
23+
├── .nojekyll # Disables Jekyll processing
24+
├── README.md # Brief explanation of the branch purpose
25+
└── {static-assets} # Other static files needed by the site
26+
```
27+
28+
## Cleanup Guidelines
29+
30+
When maintaining the `gh-pages` branch:
31+
32+
1. **Remove unnecessary files:**
33+
- Source code files (.tsx, .ts, etc.)
34+
- Development configuration files (tsconfig.json, etc.)
35+
- Scripts not needed for the deployed site
36+
- Documentation beyond a basic README
37+
38+
2. **Ensure required files exist:**
39+
- `.nojekyll` file to disable Jekyll processing
40+
- All compiled assets from the build process
41+
- A README.md explaining the branch purpose
42+
43+
## Deployment Best Practices
44+
45+
1. **Always deploy from the main branch:**
46+
- Build the website on the `main` branch
47+
- Push only the build output to `gh-pages`
48+
49+
2. **Use the provided deployment scripts:**
50+
- Scripts in `scripts/deployment/` handle the correct structure
51+
- They ensure only the necessary files are included
52+
53+
3. **Never manually edit files on gh-pages:**
54+
- All changes should be made on `main` and re-deployed
55+
- This maintains a clean separation of concerns
56+
57+
## Verifying Proper Structure
58+
59+
After deployment, verify that:
60+
1. The website functions correctly
61+
2. No unnecessary files are present
62+
3. The structure follows the guidelines above
63+
64+
## Related Documentation
65+
66+
- [GitHub Pages Branching Guide](./GITHUB_PAGES_BRANCHING_GUIDE.md)
67+
- [Deployment Documentation](./DEPLOYMENT_DOCUMENTATION.md)
68+
- [Comprehensive Deployment Guide](./COMPREHENSIVE_GUIDE.md)

docs/deployment/COMPREHENSIVE_GUIDE.md

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,12 @@ This comprehensive guide covers all aspects of deploying the Elmentor Landing Pa
2222

2323
Use our simplified deployment batch file:
2424

25-
```bash
26-
# Windows
27-
.\deploy.bat
25+
```powershell
26+
# PowerShell (recommended)
27+
./scripts/deployment/deploy.ps1
28+
29+
# Or using batch (Windows)
30+
.\scripts\deployment\deploy.bat
2831
```
2932

3033
This script will:
@@ -82,8 +85,8 @@ If assets are not loading correctly:
8285

8386
If you encounter Git "dubious ownership" errors during deployment, use:
8487

85-
```bash
86-
.\scripts\fix-git-ownership.ps1
88+
```powershell
89+
./scripts/utils/fix-git-ownership.ps1
8790
```
8891

8992
## Advanced Deployment Options

docs/deployment/DEPLOYMENT_DOCUMENTATION.md

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -11,45 +11,47 @@ The project includes several deployment scripts with varying levels of functiona
1111
### 1. Simple Deployment (Recommended)
1212

1313
**Files:**
14-
- `deploy-simple.ps1` (PowerShell)
15-
- `deploy-simple.bat` (Windows Batch)
14+
- `scripts/deployment/deploy.ps1` (PowerShell)
15+
- `scripts/deployment/deploy.bat` (Windows Batch)
1616

1717
**Key Features:**
1818
- Simple and reliable
1919
- Minimal dependencies
2020
- Handles GitHub Pages deployment efficiently
2121
- Creates a separate deployment directory to avoid git issues
2222
- Supports both GitHub CLI and direct git push methods
23+
- Follows DevOps Visions standards
2324

2425
**Usage:**
25-
```
26+
```powershell
2627
# Using PowerShell
27-
./deploy-simple.ps1
28+
./scripts/deployment/deploy.ps1
2829
2930
# Using Command Prompt
30-
deploy-simple.bat
31+
.\scripts\deployment\deploy.bat
3132
```
3233

3334
### 2. Clean Structure Deployment
3435

3536
**Files:**
36-
- `deploy-clean.ps1` (PowerShell)
37-
- `deploy-clean.bat` (Windows Batch)
37+
- `scripts/deployment/deploy-clean.ps1` (PowerShell)
38+
- `scripts/deployment/deploy-clean.bat` (Windows Batch)
3839

3940
**Key Features:**
4041
- Includes extensive pre-deployment checks
4142
- Verifies assets, dependencies, and configuration
4243
- Provides detailed feedback during deployment
4344
- Performs TypeScript error checking
4445
- Better error handling and reporting
46+
- Follows DevOps Visions standards
4547

4648
**Usage:**
47-
```
49+
```powershell
4850
# Using PowerShell
49-
./deploy-clean.ps1
51+
./scripts/deployment/deploy-clean.ps1
5052
5153
# Using Command Prompt
52-
deploy-clean.bat
54+
.\scripts\deployment\deploy-clean.bat
5355
```
5456

5557
## Deployment Process

docs/deployment/GITHUB_PAGES_BRANCHING_GUIDE.md

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,36 @@
11
# GitHub Pages & Branching Guide
22

3-
This guide explains the branch structure in this repository and how GitHub Pages deployment works.
3+
This guide explains the branch structure in this repository and how GitHub Pages deployment works, following DevOps Visions standards.
44

55
## Branch Structure
66

7-
- **`master`**: Main development branch containing the source code
8-
- **`gh-pages`**: Deployment branch containing the built application (generated output only)
7+
- **`main`**: Main development branch containing the source code, documentation, and configuration
8+
- **`gh-pages`**: Deployment branch containing only the built application (generated output only)
99

1010
## GitHub Pages Deployment
1111

1212
This project deploys to GitHub Pages using the `gh-pages` branch, which contains only the production build output from the application.
1313

1414
### Important Notes
1515

16-
1. **Never merge the `gh-pages` branch into `master`**
16+
1. **Never merge the `gh-pages` branch into `main`**
1717
- The `gh-pages` branch contains only build output and should never be merged into source branches
18-
- GitHub may suggest a "Compare & pull request" for `gh-pages``master`, but these should always be ignored
18+
- GitHub may suggest a "Compare & pull request" for `gh-pages``main`, but these should always be ignored
1919

2020
2. **Default Branch**
21-
- The repository uses `master` as the default branch
21+
- The repository uses `main` as the default branch (previously `master`)
2222
- Changing the default branch will not affect GitHub Pages, as it's configured to deploy from the `gh-pages` branch
2323

2424
3. **Deployment Process**
2525
- The deployment process builds the application and pushes the result to the `gh-pages` branch
26-
- This is handled by the scripts in the `/scripts` directory (`deploy.ps1`, `sync-gh-pages.ps1`, etc.)
26+
- This is handled by the scripts in the `/scripts/deployment` directory (`deploy.ps1`, `sync-gh-pages.ps1`, etc.)
27+
28+
4. **Standard Structure**
29+
- The `gh-pages` branch should contain only:
30+
- `index.html` (built version)
31+
- Assets directory with compiled JS/CSS
32+
- Static assets required by the website
33+
- A minimal README.md explaining the branch's purpose
2734

2835
## Automation for Branch Protection
2936

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Clean GitHub Pages Branch Structure
2+
#
3+
# This script:
4+
# 1. Checks out gh-pages branch
5+
# 2. Keeps only files needed for GitHub Pages
6+
# 3. Adds a proper README.md explaining the branch purpose
7+
# 4. Commits the changes
8+
9+
param (
10+
[switch]$Force = $false
11+
)
12+
13+
# Safety check
14+
if (-not $Force) {
15+
Write-Host "WARNING: This script will clean up the gh-pages branch, removing files not needed for deployment." -ForegroundColor Yellow
16+
Write-Host "Files that will be kept:" -ForegroundColor Cyan
17+
Write-Host "- index.html" -ForegroundColor Cyan
18+
Write-Host "- assets/ directory" -ForegroundColor Cyan
19+
Write-Host "- Static assets (images, etc.)" -ForegroundColor Cyan
20+
Write-Host "- .nojekyll file" -ForegroundColor Cyan
21+
Write-Host "- README.md" -ForegroundColor Cyan
22+
Write-Host ""
23+
Write-Host "All other files will be DELETED!" -ForegroundColor Red
24+
25+
$confirmation = Read-Host "Do you want to continue? (y/n)"
26+
if ($confirmation -ne 'y') {
27+
Write-Host "Operation cancelled." -ForegroundColor Red
28+
exit 0
29+
}
30+
}
31+
32+
# Check if we have uncommitted changes
33+
$status = git status --porcelain
34+
if ($status) {
35+
Write-Host "You have uncommitted changes. Please commit or stash them before running this script." -ForegroundColor Red
36+
exit 1
37+
}
38+
39+
# Store current branch
40+
$currentBranch = git rev-parse --abbrev-ref HEAD
41+
Write-Host "Current branch: $currentBranch" -ForegroundColor Blue
42+
43+
try {
44+
# Checkout gh-pages branch
45+
Write-Host "Checking out gh-pages branch..." -ForegroundColor Blue
46+
git checkout gh-pages
47+
48+
if ($LASTEXITCODE -ne 0) {
49+
Write-Host "Failed to checkout gh-pages branch. Aborting." -ForegroundColor Red
50+
exit 1
51+
}
52+
53+
# Create temp directory
54+
Write-Host "Creating temporary directory..." -ForegroundColor Blue
55+
$tempDir = ".\.temp\gh-pages-cleanup"
56+
if (Test-Path $tempDir) {
57+
Remove-Item -Recurse -Force $tempDir
58+
}
59+
New-Item -ItemType Directory -Force -Path $tempDir | Out-Null
60+
61+
# Copy essential files to temp directory
62+
Write-Host "Copying essential files..." -ForegroundColor Blue
63+
Copy-Item -Path "index.html" -Destination "$tempDir\" -Force
64+
Copy-Item -Path ".nojekyll" -Destination "$tempDir\" -Force
65+
66+
# Copy assets directory if it exists
67+
if (Test-Path "assets") {
68+
Copy-Item -Path "assets" -Destination "$tempDir\" -Recurse -Force
69+
}
70+
71+
# Copy other static files that might be needed
72+
foreach ($dir in @("images", "gatherings", "public", "img", "static", "fonts", "favicon.ico")) {
73+
if (Test-Path $dir) {
74+
Write-Host "Copying $dir..." -ForegroundColor Blue
75+
Copy-Item -Path $dir -Destination "$tempDir\" -Recurse -Force
76+
}
77+
}
78+
79+
# Download the gh-pages README from the main branch
80+
Write-Host "Creating README.md for gh-pages..." -ForegroundColor Blue
81+
$readmePath = "$tempDir\README.md"
82+
83+
# Copy the specialized README or use a basic one
84+
if (Test-Path "d:\Github_personal\GHPAGES_README.md") {
85+
Copy-Item -Path "d:\Github_personal\GHPAGES_README.md" -Destination $readmePath -Force
86+
} else {
87+
@"
88+
# Elmentor Landing Page (Deployed Site)
89+
90+
This branch contains the deployed version of the Elmentor Landing Page website that is served via GitHub Pages.
91+
92+
## Important Notes
93+
94+
- This is the **deployment branch** containing only built files
95+
- Do NOT make direct changes to files in this branch
96+
- Do NOT merge this branch into the `main` branch
97+
- All development should occur on the `main` branch
98+
"@ | Out-File -FilePath $readmePath -Encoding utf8
99+
}
100+
101+
# Clean gh-pages branch - remove all files except .git
102+
Write-Host "Cleaning gh-pages branch..." -ForegroundColor Blue
103+
Get-ChildItem -Path "." -Exclude @(".git", ".temp") | Remove-Item -Recurse -Force
104+
105+
# Copy files back from temp directory
106+
Write-Host "Restoring essential files..." -ForegroundColor Blue
107+
Copy-Item -Path "$tempDir\*" -Destination "." -Recurse -Force
108+
109+
# Stage the changes
110+
Write-Host "Staging changes..." -ForegroundColor Blue
111+
git add -A
112+
113+
# Commit the changes
114+
Write-Host "Committing changes..." -ForegroundColor Blue
115+
git commit -m "Clean up gh-pages branch structure to DevOps Visions standards"
116+
117+
Write-Host "GH-Pages branch structure has been cleaned up according to DevOps Visions standards." -ForegroundColor Green
118+
Write-Host "To push these changes to origin, run: git push origin gh-pages" -ForegroundColor Yellow
119+
120+
} catch {
121+
Write-Host "An error occurred: $_" -ForegroundColor Red
122+
} finally {
123+
# Return to original branch
124+
Write-Host "Returning to $currentBranch branch..." -ForegroundColor Blue
125+
git checkout $currentBranch
126+
}

0 commit comments

Comments
 (0)