GitHub Practices to Make Your Ancestors Proud

Sensible Git Practices at the Repo and Org Level

‍

I don’t know about you, but I think my children deserve to grow up in a country where every git history is clean, where branches and commit names make sense, and, yes, where you know your PR will make it to prod quickly.

‍

We have all been there. Imagine the chaos of a tech team where standards are neglected and processes are left to chance. Every day, developers grapple with confusion and the constant threat of errors creeping into their workflows. This lack of organization isn't just frustrating; it saps morale, cripples productivity, and can turn every release into a potential disaster. But it doesn’t have to be this way. Implementing transparent, robust GitHub practices can transform this chaos into a streamlined powerhouse of efficiency and innovation.

‍

The following practices work for my company and clients; I suspect they’ll work for you, too.

Repository Rules for Speed and Precision

We aim to streamline processes at the repository level for speed and efficiency. By implementing these best practices, teams can accelerate development cycles, reduce integration issues, and enhance overall productivity, making every code commit smoother and faster.  Here’s what I recommend:

‍

1. Consistent Naming Conventions: Simplify your search. Use lowercase and dash-case for repository names, and extend this clarity to branches, commits, and pull requests.
2. Trunk-Based Development: Faster and simpler. Adopt this approach for less complexity and more rapid integration, minimizing merge conflicts and all-around confusion. There are no release branches or dev (my personal favorite) branches.  Everything goes just right into master and out to prod.
3. Branch and Commit Naming: Organize your changes. Differentiate your commits and branches for features, bug fixes, and chores to keep things tidy.
4. Link and Squash PRs: some text
   1. Link your work. Enforce PR titles to include ticket numbers, enhancing traceability and context for every change.  
   2. Squash your commits: Posterity doesn’t need a record of everything you went through to put together a PR.  If someone wants to see it, they can review your PR for years. Squash it!
5. Branch Protection: Safeguard your default branch. I really shouldn’t have to say this, but I will.  Set rules to prevent direct pushes and ensure all changes pass through proper review channels.
6. No Forks: Centralize to simplify. No forking.  Everyone works off of origin.  This simplifies and speeds up collaboration.  
7. Effective Tagging: Mark your progress. Okay… this is also something I probably don't need to say. Still, here it is: Use Semver on git tags to mark releases systematically, helping you accurately track your development milestones.  
8. Hooks Please: Ensure consistency. Use Git hooks locally to minimize the times pipelines fail for stupid reasons.  Linters (and even unit tests) should run in the pre-commit hook.

Organizational Standards to Minimize Footprint

At the repo level, it’s all about speed and efficiency. At the organizational level, we implement simple, clear practices to minimize our global footprint and reduce cognitive load across teams. The goal is to limit what we have to track and how we track it.

‍

1. Use Template Repositories: Standardize setups. Use templates to ensure every new project starts with the same configurations, making new project onboarding a breeze.
2. Use .github Repository: Share critical files. Use a .github repository to propagate health files and workflows across all your projects, ensuring uniformity.
3. Maintain Documentation Standards: Keep everyone informed. Maintaining high documentation standards ensures every project is comprehensible and accessible to all stakeholders. At the organizational level, documentation standards focus on expectations for doc output (where they live), update frequency, and structure. The actual contents are best left to the individual repo contributors on a repo—and, of course, clean code (and unit tests) are the best form of documentation.
4. Use Topics: Categorize efficiently. Tag your repositories with a predefined list of topics, enhancing organization and searchability.

‍

Transform Chaos into Clarity with Rock Valley Tech

Alright, there it is.  Adopt these practices to boost your team's efficiency, win your employees' hearts, and spark your competitors' envy. 

A well-organized GitHub environment reduces errors, speeds development, and builds a more engaged and productive team. 

If you're ready to leave behind the chaos and step into a world of streamlined operations, Rock Valley Tech’s DevOps as a subscription service is here to guide you. Visit our website and schedule an introductory call to see how we can partner.

‍