diff --git a/.github/workflows/create-client-fork.yml b/.github/workflows/create-client-fork.yml index be82228..4e5cfce 100644 --- a/.github/workflows/create-client-fork.yml +++ b/.github/workflows/create-client-fork.yml @@ -3,9 +3,9 @@ # # SPDX-License-Identifier: GPL-3.0-or-later # -# GitHub Actions Workflow: Create Client Fork Implementation +# GitHub Actions Workflow: Create Client Fork (Colors Only) -name: Create Client Fork +name: Create Client Fork (Colors Only) "on": workflow_dispatch: @@ -55,6 +55,8 @@ jobs: - name: Copy custom color templates run: | echo "Copying colors_custom.css..." + mkdir -p src/media/css/colors/light + mkdir -p src/media/css/colors/dark cp templates/colors_custom.css src/media/css/colors/light/colors_custom.css cp templates/colors_custom.css src/media/css/colors/dark/colors_custom.css @@ -72,38 +74,12 @@ jobs: exit 1 fi - - name: Replace README with client fork README + - name: Apply client fork .gitignore run: | - echo "Replacing README.md..." - sed "s/\[CLIENT NAME\]/${{ inputs.client_name }}/g" CLIENT_FORK_README.md > README.md - - CURRENT_DATE=$(date +"%Y-%m-%d") - sed -i "s/\[DATE\]/${CURRENT_DATE}/g" README.md - sed -i "s/\[YOUR-FORK-URL\]/https:\/\/github.com\/${GITHUB_REPOSITORY}/g" README.md - - echo "✓ README.md replaced" - - - name: Clean up template files - run: | - echo "Removing template files..." - - if [ -f "CLIENT_FORK_README.md" ]; then - rm CLIENT_FORK_README.md - echo "✓ Removed CLIENT_FORK_README.md" - fi - - if [ -f "templates/CLIENT_FORK_README_TEMPLATE.md" ]; then - rm templates/CLIENT_FORK_README_TEMPLATE.md - echo "✓ Removed templates/CLIENT_FORK_README_TEMPLATE.md" - fi - - if [ -f "templates/README.md" ]; then - sed -i '/CLIENT_FORK_README_TEMPLATE.md/d' templates/README.md - sed -i '/Client Fork README Template/,/^---$/d' templates/README.md - echo "✓ Updated templates/README.md" - fi - - echo "✓ Keeping templates/colors_custom.css" + echo "Setting up .gitignore to track custom color files..." + cp templates/gitignore-template .gitignore + echo "✓ Applied client fork .gitignore template" + echo "✓ Custom color files will be tracked in this fork" - name: Commit changes run: | @@ -113,12 +89,10 @@ jobs: if git diff --staged --quiet; then echo "No changes to commit" else - git commit -m "Setup client fork for ${{ inputs.client_name }}" \ + git commit -m "Setup client fork for ${{ inputs.client_name }} (colors only)" \ -m "Copied colors_custom.css to src/media/css/colors/" \ - -m "Replaced README.md with CLIENT_FORK_README.md" \ - -m "Removed CLIENT_FORK_README.md" \ - -m "Removed templates/CLIENT_FORK_README_TEMPLATE.md" \ - -m "Kept templates/colors_custom.css as template" + -m "Applied client fork .gitignore template to track custom color files" \ + -m "Kept templates/colors_custom.css as reference" echo "✓ Changes committed" fi @@ -133,20 +107,23 @@ jobs: ## Client Fork Setup Complete! 🎉 ### Changes Applied - - ✓ Copied colors_custom.css to src/media/css/colors/ - - ✓ Replaced README.md - - ✓ Removed CLIENT_FORK_README.md - - ✓ Removed templates/CLIENT_FORK_README_TEMPLATE.md - - ✓ Kept templates/colors_custom.css + - ✓ Copied colors_custom.css to src/media/css/colors/light/ + - ✓ Copied colors_custom.css to src/media/css/colors/dark/ + - ✓ Applied client fork .gitignore template + - ✓ Custom color files will be tracked in this fork ### Next Steps 1. Review branch: \`${BRANCH_NAME}\` - 2. Customize colors in src/media/css/colors/ - 3. Update README.md with client details - 4. Create new repository for ${{ inputs.client_name }} - 5. Push branch to new repository + 2. Customize colors in src/media/css/colors/light/colors_custom.css + 3. Customize colors in src/media/css/colors/dark/colors_custom.css + 4. Test colors in both light and dark modes + 5. Create new repository for ${{ inputs.client_name }} + 6. Push branch to new repository + 7. In Joomla: System → Site Templates → MokoCassiopeia → Theme tab + 8. Set palette to 'Custom' and save ### Branch Information - **Branch**: \`${BRANCH_NAME}\` - **Client**: ${{ inputs.client_name }} + - **Scope**: Custom colors only EOF diff --git a/docs/CLIENT_FORK_WORKFLOW.md b/docs/CLIENT_FORK_WORKFLOW.md index 131ceaf..be8dba8 100644 --- a/docs/CLIENT_FORK_WORKFLOW.md +++ b/docs/CLIENT_FORK_WORKFLOW.md @@ -2,26 +2,25 @@ SPDX-License-Identifier: GPL-3.0-or-later - BRIEF: Documentation for client fork creation workflow + BRIEF: Documentation for client fork creation workflow (colors only) --> -# Client Fork Creation Workflow +# Client Fork Creation Workflow (Colors Only) -This document explains how to use the automated client fork creation tools to set up a new client-specific fork of MokoCassiopeia. +This document explains how to use the automated client fork creation tools to set up a new client-specific fork of MokoCassiopeia for custom color branding. --- ## Overview -The client fork creation workflow automates the process of preparing a repository for a client-specific fork. It performs the following actions: +The client fork creation workflow automates the process of preparing a repository for a client-specific color fork. It performs the following actions: 1. ✅ Copies `templates/colors_custom.css` to `src/media/css/colors/light/colors_custom.css` 2. ✅ Copies `templates/colors_custom.css` to `src/media/css/colors/dark/colors_custom.css` -3. ✅ Replaces `README.md` with customized `CLIENT_FORK_README.md` -4. ✅ Removes `CLIENT_FORK_README.md` from root -5. ✅ Removes `templates/CLIENT_FORK_README_TEMPLATE.md` -6. ✅ Updates `templates/README.md` to remove fork template references -7. ✅ Keeps `templates/colors_custom.css` as a template for reference +3. ✅ Applies client fork `.gitignore` template that tracks custom color files +4. ✅ Keeps `templates/colors_custom.css` as a reference template + +**Scope**: Client forks are limited to custom color branding only. All other customizations should be made through Joomla's template settings. --- @@ -39,7 +38,7 @@ The client fork creation workflow automates the process of preparing a repositor - Click on the "Actions" tab 2. **Run the Workflow** - - Select "Create Client Fork" from the workflow list + - Select "Create Client Fork (Colors Only)" from the workflow list - Click "Run workflow" - Fill in the required inputs: - **Client Name**: Full client name (e.g., "Acme Corporation") @@ -54,8 +53,8 @@ The client fork creation workflow automates the process of preparing a repositor 4. **Review the Branch** - Navigate to the new branch: `client-fork/{client-slug}` - Review the changes made - - The README will be customized with the client name - - Custom color files will be in place + - Custom color files will be in place and tracked + - Upstream README and documentation remain unchanged 5. **Create Client Repository** - Create a new repository for the client @@ -69,8 +68,8 @@ The client fork creation workflow automates the process of preparing a repositor - ✅ **Safe Confirmation**: Requires typing "CONFIRM" to prevent accidental runs - ✅ **Automated Branch Creation**: Creates a properly named branch automatically -- ✅ **Customized README**: Automatically fills in client name and date -- ✅ **Git Tracking**: Commits all changes with a descriptive message +- ✅ **Color File Setup**: Copies color templates to both light and dark directories +- ✅ **Git Tracking**: Custom colors tracked via client fork .gitignore - ✅ **Summary Report**: Provides a complete summary of actions taken --- @@ -137,28 +136,22 @@ The client fork creation workflow automates the process of preparing a repositor ### Files Created ``` -src/media/css/colors/light/colors_custom.css [NEW] -src/media/css/colors/dark/colors_custom.css [NEW] +src/media/css/colors/light/colors_custom.css [NEW - TRACKED] +src/media/css/colors/dark/colors_custom.css [NEW - TRACKED] ``` ### Files Modified ``` -README.md [REPLACED] -templates/README.md [UPDATED] +.gitignore [REPLACED with client fork template] ``` -### Files Removed +### Files Kept Unchanged ``` -CLIENT_FORK_README.md [DELETED] -templates/CLIENT_FORK_README_TEMPLATE.md [DELETED] -``` - -### Files Kept - -``` -templates/colors_custom.css [UNCHANGED] +README.md [UNCHANGED - upstream docs] +templates/colors_custom.css [UNCHANGED - reference template] +All other repository files [UNCHANGED] ``` --- @@ -172,26 +165,26 @@ After running the workflow or script, you should: - Edit `src/media/css/colors/dark/colors_custom.css` - Update CSS variables to match client branding -2. **Update README** - - Fill in client-specific contact information - - Add custom notes or configurations - - Update fork URL references - -3. **Test Locally** +2. **Test Locally** - Install the template in a local Joomla instance - Test light and dark modes - Verify custom colors appear correctly +3. **Enable Custom Palette in Joomla** + - Log into Joomla admin + - Navigate to System → Site Templates → MokoCassiopeia + - Under Theme tab, set palette to "Custom" + - Save and test + 4. **Create Client Repository** - Create a new repository for the client - Push the prepared branch to the new repo - Set up appropriate access controls -5. **Enable Custom Palette in Joomla** - - Log into Joomla admin - - Navigate to System → Site Templates → MokoCassiopeia - - Under Theme tab, set palette to "Custom" - - Save and test +5. **Document Customizations** + - Add a note to the repository about custom colors + - Document the client's brand color palette + - Keep reference for future updates --- @@ -203,7 +196,7 @@ After running the workflow or script, you should: **Solution**: Make sure you type "CONFIRM" (in all caps) in the confirmation field. -### Script Says "CLIENT_FORK_README.md not found" +### Script Says "colors_custom.css not found" **Problem**: Script can't find required files. @@ -235,6 +228,16 @@ git branch -D client-fork/{client-slug} ./scripts/create-client-fork.sh "Client Name - Division" ``` +### How to Make Other Customizations + +**Problem**: Need more than just color customization. + +**Solution**: Use Joomla's built-in template customization options: +- System → Site Templates → MokoCassiopeia → Custom Code tab +- Add custom HTML/CSS/JS through the template settings +- Use Joomla's module positions and layout options +- For extensive customizations, consider a full template fork (not recommended) + --- ## Examples @@ -248,7 +251,8 @@ git branch -D client-fork/{client-slug} This creates: - Branch: `client-fork/acme-corporation` -- README title: "Acme Corporation - MokoCassiopeia Custom Fork" +- Custom colors tracked in the fork +- Upstream README and docs preserved ### Example 2: Client with Multiple Words @@ -259,18 +263,18 @@ This creates: This creates: - Branch: `client-fork/global-tech-solutions-inc` -- README title: "Global Tech Solutions Inc - MokoCassiopeia Custom Fork" +- Custom color files in `src/media/css/colors/` ### Example 3: Using GitHub Actions -1. Go to Actions → Create Client Fork +1. Go to Actions → Create Client Fork (Colors Only) 2. Enter: "Mountain View Medical Center" 3. Enter: "CONFIRM" 4. Click "Run workflow" Result: - Branch: `client-fork/mountain-view-medical-center` -- README title: "Mountain View Medical Center - MokoCassiopeia Custom Fork" +- Color files ready for customization --- @@ -283,26 +287,37 @@ Result: - Don't merge client fork branches back to main 3. **Custom Colors**: - - Document color choices in README + - Document color choices in a README note or commit message - Keep a backup of custom color files - - Test in both light and dark modes + - Test in both light and dark modes before deployment 4. **Version Tracking**: - - Note the upstream version in fork README + - Note the upstream version in your fork documentation - Track when you last synced with upstream + - Use semantic versioning for your fork releases 5. **Security**: - Don't commit client-specific credentials - - Review custom code before deployment - Keep client forks private if they contain sensitive branding + - Regularly sync with upstream for security patches + +6. **Syncing with Upstream**: + - Periodically merge upstream updates to get bug fixes + - Test thoroughly after merging upstream changes + - Custom colors won't conflict with upstream updates + +7. **Limited Scope**: + - Forks are for colors only + - Use Joomla's template settings for other customizations + - Avoid modifying core template files --- ## Related Documentation -- **[CLIENT_FORK_README.md](../CLIENT_FORK_README.md)** - Full client fork guide -- **[CSS Variables](../docs/CSS_VARIABLES.md)** - Complete CSS variable reference +- **[CSS Variables](../docs/CSS_VARIABLES.md)** - Complete CSS variable reference for color customization - **[Main README](../README.md)** - MokoCassiopeia documentation +- **[Quick Start](../docs/QUICK_START.md)** - Installation and setup guide --- @@ -315,6 +330,7 @@ For issues with the workflow or script: --- -**Document Version**: 1.0 -**Last Updated**: 2026-02-20 +**Document Version**: 2.0 +**Last Updated**: 2026-03-04 +**Scope**: Colors only **Maintained by**: Moko Consulting diff --git a/scripts/create-client-fork.sh b/scripts/create-client-fork.sh index 6f6b321..966e3de 100755 --- a/scripts/create-client-fork.sh +++ b/scripts/create-client-fork.sh @@ -3,11 +3,10 @@ # # SPDX-License-Identifier: GPL-3.0-or-later # -# Script: Create Client Fork Setup +# Script: Create Client Fork Setup (Colors Only) # This script prepares the repository for a client-specific fork by: # - Copying custom color templates to the appropriate locations -# - Replacing the main README with the client fork README -# - Cleaning up template documentation files +# - Setting up .gitignore to track colors_custom.css files in the fork set -e @@ -37,11 +36,12 @@ BRANCH_NAME="client-fork/${CLIENT_SLUG}" echo "" echo "╔════════════════════════════════════════════════════════════════╗" -echo "║ MokoCassiopeia - Client Fork Setup Script ║" +echo "║ MokoCassiopeia - Client Fork Setup (Colors Only) ║" echo "╚════════════════════════════════════════════════════════════════╝" echo "" print_info "Client Name: ${CLIENT_NAME}" print_info "Branch Name: ${BRANCH_NAME}" +print_info "Scope: Custom colors only" echo "" # Confirm before proceeding @@ -53,8 +53,13 @@ if [[ ! $REPLY =~ ^[Yy]es$ ]]; then fi # Check if we're in the right directory -if [ ! -f "CLIENT_FORK_README.md" ]; then - print_error "CLIENT_FORK_README.md not found. Are you in the repository root?" +if [ ! -f "templates/colors_custom.css" ]; then + print_error "templates/colors_custom.css not found. Are you in the repository root?" + exit 1 +fi + +if [ ! -f "templates/gitignore-template" ]; then + print_error "templates/gitignore-template not found. Are you in the repository root?" exit 1 fi @@ -65,6 +70,8 @@ print_success "Branch created" # Copy custom color templates print_info "Copying colors_custom.css to light and dark mode directories..." +mkdir -p src/media/css/colors/light +mkdir -p src/media/css/colors/dark cp templates/colors_custom.css src/media/css/colors/light/colors_custom.css cp templates/colors_custom.css src/media/css/colors/dark/colors_custom.css @@ -76,46 +83,11 @@ else exit 1 fi -# Replace README with client fork README -print_info "Replacing README.md with CLIENT_FORK_README.md..." -sed "s/\[CLIENT NAME\]/${CLIENT_NAME}/g" CLIENT_FORK_README.md > README.md.new -mv README.md.new README.md - -# Update fork information section -CURRENT_DATE=$(date +"%Y-%m-%d") -sed -i.bak "s/\[DATE\]/${CURRENT_DATE}/g" README.md -sed -i.bak "s/\[YOUR-FORK-URL\]/[UPDATE-WITH-YOUR-FORK-URL]/g" README.md -rm -f README.md.bak - -print_success "README.md replaced with customized client fork README" - -# Clean up template files -print_info "Removing template documentation files..." - -if [ -f "CLIENT_FORK_README.md" ]; then - rm CLIENT_FORK_README.md - print_success "Removed CLIENT_FORK_README.md" -fi - -if [ -f "templates/CLIENT_FORK_README_TEMPLATE.md" ]; then - rm templates/CLIENT_FORK_README_TEMPLATE.md - print_success "Removed templates/CLIENT_FORK_README_TEMPLATE.md" -fi - -# Update templates/README.md -if [ -f "templates/README.md" ]; then - # Create a backup - cp templates/README.md templates/README.md.bak - - # Remove references to CLIENT_FORK_README_TEMPLATE.md - sed '/CLIENT_FORK_README_TEMPLATE.md/d' templates/README.md > templates/README.md.tmp - mv templates/README.md.tmp templates/README.md - rm -f templates/README.md.bak - - print_success "Updated templates/README.md" -fi - -print_success "Keeping templates/colors_custom.css as template" +# Copy template .gitignore to root +print_info "Setting up .gitignore to track custom color files..." +cp templates/gitignore-template .gitignore +print_success "Copied templates/gitignore-template to .gitignore" +print_info "Custom color files will be tracked in this fork" # Show git status echo "" @@ -128,14 +100,13 @@ read -p "Commit these changes? (yes/no): " -r echo if [[ $REPLY =~ ^[Yy]es$ ]]; then git add . - git commit -m "Setup client fork for ${CLIENT_NAME} + git commit -m "Setup client fork for ${CLIENT_NAME} (colors only) - Copied colors_custom.css to src/media/css/colors/light/ and dark/ -- Replaced README.md with customized CLIENT_FORK_README.md -- Removed CLIENT_FORK_README.md and templates/CLIENT_FORK_README_TEMPLATE.md -- Kept templates/colors_custom.css as template +- Applied client fork .gitignore template to track custom color files +- Kept templates/colors_custom.css as reference template -This commit prepares the repository for ${CLIENT_NAME}'s custom fork." +This commit prepares the repository for ${CLIENT_NAME}'s custom colors." print_success "Changes committed successfully" @@ -153,16 +124,16 @@ echo "" echo "Changes Applied:" print_success "Copied colors_custom.css to src/media/css/colors/light/" print_success "Copied colors_custom.css to src/media/css/colors/dark/" -print_success "Replaced README.md with customized client fork README" -print_success "Removed CLIENT_FORK_README.md" -print_success "Removed templates/CLIENT_FORK_README_TEMPLATE.md" -print_success "Kept templates/colors_custom.css as template" +print_success "Applied client fork .gitignore template" +print_success "Custom color files will be tracked in this fork" echo "" echo "Next Steps:" echo "1. Review the changes in branch: ${BRANCH_NAME}" echo "2. Customize colors in src/media/css/colors/light/colors_custom.css" echo "3. Customize colors in src/media/css/colors/dark/colors_custom.css" -echo "4. Update README.md with client-specific details" +echo "4. Test the colors in both light and dark modes" echo "5. Create a new repository for ${CLIENT_NAME}" echo "6. Push this branch to the new repository" +echo "7. In Joomla: System → Site Templates → MokoCassiopeia → Theme tab" +echo "8. Set palette to 'Custom' and save" echo "" diff --git a/templates/README.md b/templates/README.md index b5b78e3..bf3b9a3 100644 --- a/templates/README.md +++ b/templates/README.md @@ -7,7 +7,7 @@ # MokoCassiopeia Template Files -This directory contains template files for client customizations and custom code forks. +This directory contains template files for client color customizations. --- @@ -31,19 +31,15 @@ A comprehensive template for creating custom color schemes. This template includ --- -### Client Fork README Template +### Client Fork .gitignore Template -**File**: `CLIENT_FORK_README_TEMPLATE.md` +**File**: `gitignore-template` -A simplified README template for client-specific forks. Use this as a starting point for documenting your customizations. +A .gitignore template for client forks that ensures custom color files are tracked in the fork repository while maintaining proper ignore rules for other files. **Usage**: -1. Copy this file to the root of your fork repository as `README.md` -2. Replace `[CLIENT NAME]` with your client's name -3. Fill in brand colors and contact information -4. Add client-specific notes and configurations - -**For Comprehensive Fork Setup**: See [CLIENT_FORK_README.md](../CLIENT_FORK_README.md) for the complete client fork guide. +- Automatically applied when using the client fork creation workflow +- Can be manually copied to `.gitignore` in client fork repositories --- @@ -53,9 +49,9 @@ A simplified README template for client-specific forks. Use this as a starting p If you're creating a custom fork of MokoCassiopeia for a specific client: -1. **Start with the full guide**: Read [CLIENT_FORK_README.md](../CLIENT_FORK_README.md) +1. **Use the automated workflow**: See [CLIENT_FORK_WORKFLOW.md](../docs/CLIENT_FORK_WORKFLOW.md) 2. **Set up custom colors**: Use `colors_custom.css` as your starting point -3. **Document your fork**: Copy `CLIENT_FORK_README_TEMPLATE.md` to your fork +3. **Test thoroughly**: Verify colors in both light and dark modes ### Custom Colors Only @@ -70,12 +66,13 @@ If you just need custom colors without forking: ## 📚 Additional Resources - **[Main README](../README.md)** - MokoCassiopeia features and installation -- **[Client Fork Guide](../CLIENT_FORK_README.md)** - Complete guide for client forks +- **[Client Fork Workflow](../docs/CLIENT_FORK_WORKFLOW.md)** - Automated fork setup guide - **[CSS Variables Reference](../docs/CSS_VARIABLES.md)** - All available CSS variables - **[Development Guide](../docs/JOOMLA_DEVELOPMENT.md)** - Development workflows --- **Template Directory**: `/templates/` -**Version**: 03.06.03 +**Version**: 03.08.04 +**Scope**: Colors only **Maintained by**: Moko Consulting diff --git a/templates/gitignore-template b/templates/gitignore-template new file mode 100644 index 0000000..eb200ef --- /dev/null +++ b/templates/gitignore-template @@ -0,0 +1,106 @@ +# MokoCassiopeia Client Fork .gitignore Template +# This file is copied to client forks to ensure custom color files are tracked + +# DO NOT ignore custom color files in client forks +# These files should be tracked to preserve client-specific branding +# +# The files below are intentionally NOT ignored: +# src/media/css/colors/light/colors_custom.css +# src/media/css/colors/dark/colors_custom.css + +# ============================================================ +# Environment and secrets +# ============================================================ +.env +.env.local +.env.*.local +*.local.php +*.secret.php +configuration.php +configuration.*.php +configuration.local.php +conf/conf.php +conf/conf*.php +secrets/ +*.secrets.* + +# ============================================================ +# Logs, dumps and databases +# ============================================================ +*.db +*.db-journal +*.dump +*.log +*.pid +*.seed +*.sql +*.sql.gz +*.sqlite +*.sqlite3 + +# ============================================================ +# OS / Editor / IDE cruft +# ============================================================ +.DS_Store +Thumbs.db +desktop.ini +Thumbs.db:encryptable +ehthumbs.db +ehthumbs_vista.db +$RECYCLE.BIN/ +System Volume Information/ +*.lnk +Icon? +.idea/ +.settings/ +.vscode/* +!.vscode/tasks.json +!.vscode/settings.json.example +!.vscode/extensions.json +*.code-workspace + +# ============================================================ +# Package manager and dependencies +# ============================================================ +node_modules/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* +lerna-debug.log* +*.tgz +package-lock.json +yarn.lock +pnpm-lock.yaml +vendor/ + +# ============================================================ +# Build artifacts and temporary files +# ============================================================ +dist/ +build/ +.cache/ +*.tmp +*.temp +*.swp +*.swo +*~ +.#* +\#*# + +# ============================================================ +# Test and coverage +# ============================================================ +tests/_output/ +coverage/ +.nyc_output/ +phpunit.xml +.phpunit.result.cache + +# ============================================================ +# Joomla specific +# ============================================================ +administrator/cache/ +cache/ +tmp/ +logs/