Maintaining Consistency Between development and src Branches
The development and src branches should maintain a high degree of consistency, particularly with core project files like .eleventy.js, package.json, and .gitignore. This consistency simplifies the deployment process and reduces the potential for errors.
Rationale
Simplified Workflow: Consistent configurations across branches minimize the need for branch-specific adjustments, streamlining the development and deployment cycles.
Reduced Errors: Identical configurations reduce the risk of unexpected behavior due to discrepancies between branches.
Maintainability: A consistent structure makes the project easier to understand and maintain, especially for collaborative projects.
package.json Consistency
The package.json file, which defines project dependencies and scripts, should be identical across both branches.
While certain scripts (e.g., clean) may be more relevant for local development, maintaining consistency avoids confusion and potential issues during GitHub Actions builds.
When adding new dependencies or modifying scripts, ensure that these changes are reflected in both branches.
.eleventy.js and .gitignore Consistency
The .eleventy.js file should also be identical across both branches. The input and output directories must match.
The .gitignore file must also be identical.
Efficiently Updating the src Branch
When updating the src branch with changes from the development branch, it's crucial to avoid copying the entire development branch's contents. This can lead to unintended changes and clutter.
Recommended Workflow
Develop and Test in development: Make all changes and test them thoroughly in the development branch.
Use a "Stash" Folder:
Create a "stash" folder outside your repository directory.
Copy only the changed or added files from the development branch to the "stash" folder.
Switch to src Branch: Switch to the src branch in GitHub Desktop.
Copy from "Stash" to src: Copy the files from the "stash" folder to the src branch.
Commit and Push: Commit the changes in GitHub Desktop with a clear message, and push them to the remote src branch.
Rationale
Explicit Control: This method gives you explicit control over which files are transferred.
Avoids Unintended Changes: It prevents accidental copying of unnecessary files (e.g., _site, node_modules).
Clear History: It maintains a clean and organized commit history in the src branch.
Key Considerations
Regular Inspections: Regularly inspect your branches in GitHub Desktop and on GitHub.com to ensure they are consistent with your intended structure.
Branch Awareness: Always be aware of which branch you are currently working on to avoid accidental commits or file transfers.
Version Control Best Practices: Adhere to version control best practices to maintain a clean and organized repository.
By incorporating these guidelines into your documentation, you'll provide a comprehensive understanding of branch management and best practices for your 11ty project.