version control (source control)

Version control (source control) helps you track changes over time, collaborate safely, and roll back mistakes when something goes wrong. A good workflow makes it easy to review changes, keep a clean history, and ship from a known-good branch.

When it comes to working with Git for version control, you can follow the best practices below:

  • Commit small, self-contained changes. Keep each commit focused on one logical change so it’s easy to review, revert, and bisect.
  • Write clear commit messages. Summarize what changed and why it changed so your history stays understandable over time.
  • Branch for work and merge via pull requests. Do day-to-day development on short-lived branches and merge back through a PR to enable discussion and review.
  • Protect your main branch. Require pull requests (PRs), passing status checks, and reviews before merging into main to reduce accidental breakage.
  • Run automated checks on every change. Attach tests, linting, and security checks to PRs so problems are caught before merging.
  • Ignore generated files, local configuration, and sensitive data. Set up and commit a per-project .gitignore file so you don’t accidentally track build artifacts, caches, or local settings.
  • Tag releases with annotated tags. Use annotated tags to mark release points and keep versioned history easy to find.
  • Sync frequently and resolve conflicts early. Pull, rebase, and merge often so you deal with small or no conflicts instead of large, painful ones.
  • Avoid committing secrets. Keep credentials out of your repository by using environment-injected configuration and a secrets manager.
  • Document your workflow. Write down how your team branches, reviews, merges, and releases so contributors follow the same rules.

To see these ideas in practice, compare the following two workflows for making a change.

🔴 Avoid this:

Shell 
$ git checkout main
$ # edit files...
$ git add -A
$ git commit -m "updates"
$ git push origin main

This approach bypasses code review, makes it easy to push broken changes to the main branch. It also leaves you with a vague commit history because of a generic commit message.

✅ Favor this:

Shell 
$ git switch -c feat/better-login-errors
$ # edit files...
$ git add -A
$ git commit -m "Improve login error messages"
$ git push -u origin feat/better-login-errors

Open a pull request for feat/better-login-errors and merge it only after required checks pass and the PR is reviewed.

Introduction to Git and GitHub for Python Developers

Tutorial

Introduction to Git and GitHub for Python Developers

What is Git, what is GitHub, and what's the difference? Learn the basics of Git and GitHub from the perspective of a Pythonista in this tutorial.

basics tools

For additional information on related topics, take a look at the following resources:

By Leodanis Pozo Ramos • Updated Feb. 3, 2026
Python Best Practices Share Feedback