Best Practices

Best Practices Overview

A reliable deployment workflow is not only about knowing the commands. It is also about developing consistent habits when creating branches, committing changes, reviewing work, and deploying to production.

The practices in this chapter are organized around the major stages of the workflow:

Branch Strategy

A clear branch strategy keeps development work separated from production code and provides a predictable path for testing and releasing changes.

Keep main stable

The main branch should represent the version of the project that is ready for production deployment.

Avoid using main as the place where unfinished features are developed.

Use feature branches

Create a separate branch when developing a new feature or making an isolated change.

git switch main
git pull
git switch -c feature/menu

Work on the feature branch, test the changes, and commit them before creating a Pull Request.

Use descriptive branch names

Branch names should make their purpose clear.

feature/menu
feature/contact-form
fix/mobile-navigation
fix/footer-link

Keep feature branches focused

A feature branch should normally contain one related piece of work rather than several unrelated changes.

main
↓
feature branch
↓
build and test
↓
commit
↓
Pull Request
↓
main

Delete completed feature branches

Once a feature has been merged and the branch is no longer needed, remove it to keep the repository organized.

git branch -d feature/menu

Quick Reference

Commit Strategy

A good commit strategy makes project history easier to understand, review, and maintain. Each commit should represent a clear and logical change.

Keep commits focused

Avoid combining unrelated changes into one commit. For example, a navigation fix and a new feature can normally be separate commits.

git add js/navigation.js
git commit -m "Fix mobile navigation"

git add pages/menu.html
git commit -m "Add menu page"

Write meaningful commit messages

A commit message should explain what the commit changed.

git commit -m “Add coffee menu section”

Avoid vague messages such as:

git commit -m "update"
git commit -m "changes"
git commit -m "stuff"

Review before committing

Inspect your changes before creating the commit.

git status
git diff

After staging, review the exact content that will become part of the commit.

git add .
git diff --staged

Commit working changes regularly

Avoid keeping a large amount of work uncommitted for a long period. Smaller logical commits make it easier to identify when a problem was introduced.

Avoid unnecessary history rewriting

Commands such as git commit –amend and git reset can modify local history. They are useful in appropriate situations, but should be used carefully after commits have been pushed.

A practical commit workflow

git status
git diff
git add .
git diff --staged
git commit -m "Describe the change"
git log --oneline

Quick Reference

Pull Requests

Pull Requests provide a controlled way to review changes before they are merged into the production branch.

Keep Pull Requests focused

A Pull Request should normally contain one feature, fix, or closely related group of changes.

Avoid combining unrelated features and fixes into the same Pull Request.

Use a clear title

The title should clearly describe what the Pull Request changes.

Add coffee menu section
Fix mobile navigation
Update deployment configuration

Describe the change

The Pull Request description should provide enough information for someone else to understand what changed and why.

Useful information can include:

• What was changed
• Why the change was made
• How the change was tested
• Anything that still needs attention

Review the changed files

Before merging, inspect the files changed by the Pull Request and confirm that the changes are expected.

Check the deployment

When Cloudflare Pages creates a preview deployment for the feature branch, test the preview before merging.

This gives you an opportunity to identify problems before the changes reach the production branch.

Merge only after review

Once the changes have been reviewed and the required checks have passed, the Pull Request can be merged into the production branch.

feature branch
    ↓
Pull Request
    ↓
Review
    ↓
Preview deployment
    ↓
Merge
    ↓
main
    ↓
Production

Quick Reference

Secrets

Secrets are sensitive values such as API keys, access tokens, passwords, and private credentials. They should never be committed to a Git repository.

Never put secrets in source code

Avoid placing sensitive values directly inside HTML, CSS, JavaScript, configuration files, or other files that are committed to Git.

For example, do not commit code containing a real secret like this:

const API_KEY = “your-real-secret-key”;

Never commit secret files

Files containing local credentials or environment-specific secrets should not be committed to the repository.

A common example is an environment file:

.env

Use environment variables

Applications that require secrets should normally read them from environment variables or another appropriate secret-management mechanism rather than storing them directly in source code.

API_KEY=your-secret-value

The actual secret value should remain outside the repository.

Add secret files to .gitignore

If a local environment file should never be committed, add it to .gitignore.

.env
.env.local
.env.*.local

If a secret is accidentally committed

Treat the exposed secret as compromised. Do not assume that deleting the file in a later commit makes the secret safe again.

The appropriate response is to revoke or rotate the exposed credential and then remove the sensitive data from the repository as appropriate.

Keep production secrets separate

Production credentials should not be copied into source files or committed to the repository. Store them using the environment or secret configuration provided by the deployment platform or application architecture.

Quick Reference

.gitignore

The .gitignore file tells Git which files and directories should not be tracked in the repository. It is especially useful for local configuration files, generated files, dependencies, and secrets.

Create a .gitignore file

Create a file named exactly:

.gitignore

The file normally sits at the root of the project, alongside files such as index.html and the .git directory.

Common entries

A web project may need to ignore files such as local environment files, operating-system files, and generated dependencies.

# Environment files
.env
.env.local
.env.*.local

# Dependencies
node_modules/

# Build output
dist/

# Operating system files
.DS_Store
Thumbs.db

Check what Git is tracking

After creating or updating .gitignore, use:

git status

Files matching the ignore rules should normally no longer appear as untracked files.

.gitignore does not affect tracked files

If a file was already committed to Git, adding it to .gitignore does not automatically stop Git from tracking it.

You must first remove it from Git’s tracking while keeping the local file:

git rm –cached filename

Then commit the change.

git add .gitignore
git commit -m "Ignore local configuration file"

Keep .gitignore appropriate for the project

Do not blindly copy a large .gitignore file without understanding what it excludes. Ignore files and directories that should genuinely remain outside the repository.

Quick Reference

Production Safety

Production is the live version of your website. Changes that reach production can affect real visitors, so the deployment workflow should include deliberate checks before and after release.

Keep the production branch stable

Treat main as the branch that represents production-ready code.

Develop new features in feature branches and merge them into main only after they have been reviewed and tested.

Test before merging

Test the feature locally before creating the Pull Request. When a Cloudflare Pages preview is available, test the deployed preview as well.

Local project
    ↓
Local testing
    ↓
Commit
    ↓
Push
    ↓
Preview deployment
    ↓
Review
    ↓
Merge

Review the Pull Request

Before merging, review the changed files and confirm that the Pull Request contains only the intended changes.

Pay particular attention to configuration files, environment-related changes, and files that could affect the production build.

Confirm the production deployment

After merging into main, check the Cloudflare Pages deployment and confirm that it completed successfully.

Do not assume that a successful GitHub merge automatically means that the production deployment succeeded.

Verify the live website

After deployment, open the production URL and verify the important parts of the website.

Depending on the project, this may include:

• Main navigation
• Important pages
• Images and assets
• Forms and links
• Mobile layout
• Custom domain and HTTPS

Keep a rollback path

Know how to identify the previous successful production deployment. If a newly deployed version causes a problem, having a known-good deployment makes recovery easier.

Production checklist