Menu ▾ ▴

BEST_PRACTICES

Robert Trenaman

Best Practices Guide

This guide covers recommended workflows and best practices for using GitHub Commander effectively.

Git Workflow Best Practices

Commit Often

Why: Small, frequent commits make it easier to:

  • Track changes
  • Revert mistakes
  • Understand history
  • Collaborate with others

How:

  • Commit after each logical change
  • Don't wait until "it's perfect"
  • Use descriptive commit messages

Use Meaningful Commit Messages

Good Examples:

  • "Add user authentication feature"
  • "Fix login bug with special characters"
  • "Update dependencies to latest versions"

Bad Examples:

  • "update files"
  • "fix stuff"
  • "wip"

Format: Consider using conventional commits:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • style: - Code style changes
  • refactor: - Code refactoring
  • test: - Adding tests
  • chore: - Maintenance tasks

Use Branches

Workflow:

  1. Create feature branch: feature/add-login
  2. Work on feature
  3. Commit changes
  4. Test thoroughly
  5. Merge to main
  6. Delete feature branch

Benefits:

  • Isolate changes
  • Easy to revert
  • Parallel development
  • Clean history

Pull Before Push

Why: Avoid conflicts and ensure you have latest changes.

When: Always before pushing to shared branches.

How:

  1. Pull latest changes
  2. Resolve conflicts if any
  3. Test after merge
  4. Then push

Repository Management

Repository Organization

Naming Conventions:

  • Use descriptive names
  • Use kebab-case: my-awesome-project
  • Avoid special characters
  • Keep it concise

Structure:

~/github-projects/
├── personal/
│   ├── website
│   └── scripts
└── work/
    ├── project-a
    └── project-b

Repository Hygiene

Keep repositories clean:

  • Remove unused branches
  • Archive old projects
  • Update README files
  • Maintain CHANGELOG
  • Remove sensitive data

File Management

File Naming

Guidelines:

  • Use descriptive names
  • Use lowercase with hyphens
  • Avoid spaces
  • Include version in binaries

Examples:

  • user-authentication.py ✓
  • UserAuthentication.py ✗
  • user authentication.py ✗

Directory Structure

Organize files logically:

project/
├── src/
├── tests/
├── docs/
├── assets/
└── README.md

Large Files

Handle large files properly:

  • Use Git LFS for files > 100 MB
  • Compress images before upload
  • Use external storage for binaries
  • Document where large assets are stored

Wiki Management

Documentation Structure

Create a navigation hierarchy:

  • Home/Index page as main navigation
  • Link related pages together
  • Use consistent heading levels
  • Include table of contents

Content Guidelines

Write clear documentation:

  • Use simple language
  • Include examples
  • Add screenshots where helpful
  • Keep it up to date
  • Review regularly

Wiki Maintenance

Keep wikis current:

  • Update when features change
  • Remove outdated information
  • Review quarterly
  • Get feedback from users

GitHub Pages

Deployment Workflow

Before deploying:

  1. Test locally
  2. Review build output
  3. Check all links
  4. Verify images load
  5. Test on multiple browsers

After deploying:

  1. Test live site
  2. Check analytics
  3. Monitor for errors
  4. Gather user feedback

Site Performance

Optimize for performance:

  • Minimize file sizes
  • Optimize images
  • Use CDN for assets
  • Enable caching
  • Minify CSS/JS

Content Strategy

Plan your content:

  • Create content calendar
  • Write for your audience
  • Use clear headings
  • Include call-to-actions
  • Update regularly

Package Management

Versioning

Follow semantic versioning:

  • MAJOR.MINOR.PATCH (e.g., 1.2.3)
  • Increment MAJOR for breaking changes
  • Increment MINOR for new features
  • Increment PATCH for bug fixes

Example progression:

  • 1.0.0 → 1.0.1 → 1.1.0 → 2.0.0

Package Quality

Before publishing:

  • Write comprehensive documentation
  • Include usage examples
  • Add tests
  • Update README
  • Verify dependencies
  • Check for security issues

Release Process

Checklist before release:

  1. Update version number
  2. Update CHANGELOG
  3. Run all tests
  4. Update documentation
  5. Tag the release
  6. Create GitHub release
  7. Publish package
  8. Announce to users

Security Best Practices

Token Management

Secure your GitHub token:

  • Never share your token
  • Don't commit tokens to repositories
  • Use short expiration periods (30-90 days)
  • Rotate tokens regularly
  • Revoke unused tokens

Sensitive Data

Never commit:

  • API keys
  • Passwords
  • Certificates
  • Personal information
  • Configuration secrets

Use instead:

  • Environment variables
  • Secret management tools
  • .env files (in .gitignore)
  • Encrypted secrets

Access Control

Manage permissions:

  • Review collaborators regularly
  • Use least privilege principle
  • Enable 2FA on GitHub
  • Review third-party access
  • Audit repository access

Collaboration

Code Review

Before merging:

  • Request code reviews
  • Address feedback
  • Test changes
  • Update documentation
  • Communicate changes

Communication

Keep team informed:

  • Use clear commit messages
  • Write descriptive PRs
  • Update issue trackers
  • Document breaking changes
  • Announce major updates

Conflict Resolution

Handle conflicts gracefully:

  • Communicate before making changes
  • Use feature branches
  • Resolve conflicts promptly
  • Test after merging
  • Keep main stable

Backup and Recovery

Regular Backups

Backup strategy:

  • Export configuration regularly
  • Backup important repositories
  • Keep offline copies
  • Document backup process
  • Test restore procedure

Disaster Recovery

Plan for failures:

  • Have offline copies
  • Document recovery steps
  • Keep contact information
  • Test recovery process
  • Learn from incidents

Performance

Application Performance

Keep GitHub Commander fast:

  • Close unused tabs
  • Clear cache periodically
  • Don't overload with large files
  • Keep repositories manageable
  • Update regularly

Workflow Efficiency

Optimize your workflow:

  • Learn keyboard shortcuts
  • Use batch operations
  • Automate repetitive tasks
  • Customize settings
  • Use templates

Continuous Improvement

Learning

Stay updated:

  • Read documentation
  • Follow best practices
  • Learn from others
  • Attend workshops
  • Share knowledge

Feedback

Provide feedback:

  • Report bugs
  • Suggest features
  • Share use cases
  • Help others
  • Contribute to project

Checklist for New Projects

When starting a new project:

  1. Setup:
  2. [ ] Create repository
  3. [ ] Initialize with README
  4. [ ] Add .gitignore
  5. [ ] Choose license

  6. [ ] Configure settings

  7. Development:

  8. [ ] Create feature branch
  9. [ ] Set up development environment
  10. [ ] Write initial code
  11. [ ] Add tests

  12. [ ] Document setup

  13. Collaboration:

  14. [ ] Add collaborators
  15. [ ] Set up branch protection
  16. [ ] Configure CI/CD
  17. [ ] Create project board

  18. [ ] Define workflow

  19. Documentation:

  20. [ ] Write README
  21. [ ] Create wiki
  22. [ ] Add examples
  23. [ ] Document API

  24. [ ] Create guides

  25. Release:

  26. [ ] Tag version
  27. [ ] Create release
  28. [ ] Publish package
  29. [ ] Announce
  30. [ ] Monitor feedback
auth0 logo