diff --git a/docs/BestPractices.md b/docs/BestPractices.md new file mode 100644 index 00000000..653f4ac1 --- /dev/null +++ b/docs/BestPractices.md @@ -0,0 +1,54 @@ +Focus on development workflows, coding standards, and Git flow practices. Include sections for each aspect of Git flow, coding standards, and other technical best practices our /team should follow. + +### 1. **Feature Branches** + +- **Start New Features:** When beginning work on a new feature, create a feature branch off the `develop` (or `preview`, if you've chosen to rename it, which we did) branch. Use the convention `feature/your-feature-name`. +- **Finish Features:** Once a feature is completed and tested, merge it back into the `develop` branch. Delete the feature branch if it's no longer needed. + +### 2. **Develop and Preview Branch** + +- **Continuous Integration:** Regularly push changes from feature branches into this branch to integrate and test new developments. If you're using `preview` as your integration branch, this serves as a live staging area for your team to review. + +### 3. **Release Branches** + +- **Prepare Releases:** When you're ready to prepare a new release, create a release branch off `develop`. Use the naming convention `release/x.y.z` based on your versioning. +- **Finalize and Merge:** After final testing and adjustments, merge the release branch into `main` (or `master`) and back into `develop` to capture any last-minute changes made during the release process. Tag the merge into `main` with the version number. + +### 4. **Hotfix Branches** + +- **Urgent Fixes:** For urgent fixes to your production code, create a hotfix branch directly off `main`. Name it using the convention `hotfix/urgent-fix-name`. +- **Merge Back:** Once the fix is complete, merge the hotfix branch into both `main` and `develop` (or `preview`), ensuring that the fix is incorporated into future releases. + +### 5. **Main Branch** + +- **Production Ready:** The `main` branch represents the production-ready state of your project. Only merge into `main` from release or hotfix branches. + +### 6. **Version Tagging** + +- **Tag Releases:** When you merge a release into `main`, tag the commit with the version number to mark the release point. If you've set up a `version/` prefix for tags, include it in your tag name. + +### Best Practices + +- **Regular Pulls:** Regularly pull changes from the remote to keep your local branches up to date and minimize merge conflicts. +- **Branch Cleanup:** Delete branches after merging them to keep your repository clean and manageable. +- **Communication:** Ensure all team members are familiar with the Git flow process and the roles of different branches. Clear communication is key to avoiding confusion. + +If you've fast-forwarded the `preview` branch to the last commit of the `main` branch and then checked out to the `preview` branch, you've effectively synchronized the `preview` branch with the current state of `main`. This setup positions the `preview` branch to receive all future updates and changes intended for pre-production or staging review before they are merged into `main`, aligning with the workflow you seem to be establishing. + +### Moving Forward with Updates on the `preview` Branch: + +1. **Committing to `preview`:** With the `preview` branch checked out, any new commits you make will now be part of the `preview` branch. This is ideal for introducing and testing new features, bug fixes, or other changes without affecting the production-ready `main` branch. + +2. **Review and Testing:** Use the `preview` branch as a staging area to review changes, conduct tests, and ensure everything works as expected in an environment that mirrors production as closely as possible. + +3. **Pull Requests for Merging:** When you're satisfied with the changes in the `preview` branch, create a pull request (PR) to merge these changes into `main`. This PR process facilitates code review and discussion among team members, ensuring that only thoroughly vetted changes make their way to production. + +4. **Continuous Deployment with Vercel:** If your project is integrated with Vercel, remember that Vercel automatically creates preview deployments for every push to branches other than `main`. This means that pushing changes to the `preview` branch will generate a preview deployment that you can share with your team or stakeholders for feedback. + +5. **Keeping `preview` Updated:** Periodically, you may want to sync the `preview` branch with the `main` branch to ensure it reflects the latest production state. This can be done through a fast-forward merge from `main` to `preview`, similar to what you've already done, or through a regular merge if the branches have diverged significantly. + +6. **Communication:** Ensure that all team members are aware of the workflow and understand that the `preview` branch is where updates should be pushed for pre-production review. + +This workflow allows your team to efficiently manage and review changes in a controlled environment, reducing the risk of introducing errors into the production codebase. + +By adhering to these practices, you can leverage Git flow to streamline your development process, improve collaboration, and manage releases more effectively.