Learn how to track and document changes and issues in your open-source software projects using version control systems. Find out how to choose, use, and share your VCS effectively.

Linux Kernel development has helped me a lot in framing my commit messages as well as descriptions. There are strict guidelines given out by the community to follow, even before pushing a single patch on lore. Never forget to review patchset before pushing.

Establishing a specific workflow benefits both contributors and maintainers. This workflow could include a pipeline, code review, and deployment setup. Such a workflow offers the added advantage of clear visibility into where and why a workflow fails, what stage it currently is at, etc. helping stakeholders quickly identify and address issues.

Last updated on Aug 17, 2024

How do you track and document changes and issues in open-source version control systems?

If you work on open-source software projects, you know how important it is to track and document changes and issues in your code. Version control systems (VCS) are tools that help you manage the history, collaboration, and quality of your software. But how do you use them effectively and efficiently? In this article, we will cover some best practices and tips for tracking and documenting changes and issues in open-source version control systems.

1 Choose a suitable VCS

There are many VCS options available, such as Git, Subversion, Mercurial, and Bazaar. Each one has its own features, advantages, and disadvantages. You should choose a VCS that suits your project's needs, goals, and preferences. Some factors to consider are: the size and complexity of your project, the frequency and type of changes, the number and location of contributors, the level of security and privacy, and the integration with other tools and platforms.

Add your perspective

Alexandra McCoy
Report contribution
The initial mention of many VCS options being available is important. Before choosing a suitable option, you should likely understand the use case and requirements for the projects that you are working on, and then identify the appropriate solution. There is nothing wrong with becoming a subject matter expert for one solution, but always stay up to date with what is happening to be able to be flexible in the products and tooling that you work on is an attractive skill set and keeps you competitive in today's industry.

Like
Rémy Wehrung
Report contribution
De nombreux systèmes de contrôle de version (Git, Subversion, Mercurial, Bazaar) existent, avec leurs propres caractéristiques. Le choix dépend de la taille du projet, de la fréquence des changements, du nombre de contributeurs, des besoins de sécurité et d'intégration.

Translated

Like

2 Follow a consistent workflow

A workflow is a set of rules and guidelines that define how you use your VCS to create, update, and merge changes in your code. A good workflow should help you maintain a clear and organized history, avoid conflicts and errors, and facilitate collaboration and communication. There are different types of workflows, such as centralized, feature branch, fork and pull, and Gitflow. You should choose a workflow that matches your project's structure, scope, and culture, and follow it consistently throughout the project.

Add your perspective

Pratyay Dhond

Turning my coding blunders into posts & puns | Ex-Intern @ Arcesium 24' | COEP 25' | GPN 22'
Report contribution
Establishing a specific workflow benefits both contributors and maintainers. This workflow could include a pipeline, code review, and deployment setup. Such a workflow offers the added advantage of clear visibility into where and why a workflow fails, what stage it currently is at, etc. helping stakeholders quickly identify and address issues.

Like
Rémy Wehrung
Report contribution
Un flux de travail définit les règles d'utilisation du système de contrôle de version pour créer, mettre à jour et fusionner les modifications de code. Il doit faciliter un historique clair, éviter les conflits et favoriser la collaboration.

Translated

Like

3 Write clear and descriptive commit messages

A commit message is a short text that summarizes the changes you made in a commit. A commit is a snapshot of your code at a certain point in time. A good commit message should explain what you did, why you did it, and how it affects the project. It should also follow a standard format, such as using the imperative mood, starting with a capital letter, and limiting the length to 50 characters. A clear and descriptive commit message helps you and others understand the history and purpose of your changes, and makes it easier to review and debug your code.

Add your perspective

Saalim Quadri

AOSP Engineer @Vispero | LFX'23 | Linux Kernel | Android | Frameworks | Firmware | Platform
Report contribution
Whilst documenting functions are an important thing, having a good commit description and consistent message is an important aspect. It helps in tracking feature additions/updates or bug fixed and upstreams.

Like
Rémy Wehrung
Report contribution
Un message de validation résume les modifications apportées au code à un instant donné. Il doit expliquer clairement ce qui a été fait, pourquoi et comment, en suivant un format standard pour faciliter la compréhension et le débogage.

Translated

Like

4 Use tags and branches to mark milestones and versions

A tag is a label that you attach to a specific commit to mark a milestone or a version in your project. For example, you can use tags to indicate releases, patches, or beta versions. A branch is a separate line of development that you create from a commit to work on a new feature, bug fix, or experiment. For example, you can use branches to isolate changes from the main branch, test different ideas, or collaborate with others. Tags and branches help you organize and manage your code, and allow you to switch between different states of your project.

Add your perspective

Rémy Wehrung
Report contribution
Les balises marquent des jalons ou versions du projet, tandis que les branches créent des lignes de développement distinctes pour de nouvelles fonctionnalités ou corrections. Elles permettent d'organiser le code et de basculer entre différents états.

Translated

Like

5 Track and document issues using issue trackers

An issue is a problem, request, or question that arises during the development of your project. For example, an issue can be a bug, a feature, a enhancement, or a question. An issue tracker is a tool that helps you track and document issues in your project. It allows you to create, assign, prioritize, categorize, comment, and resolve issues. It also provides a history and a status of each issue, and notifies you of any changes or updates. Issue trackers help you monitor and improve the quality of your code, and communicate and collaborate with others.

Add your perspective

Rémy Wehrung
Report contribution
Un problème représente un bogue, une fonctionnalité ou une question survenant durant le développement. Un outil de suivi des problèmes permet de créer, assigner, prioriser et documenter les problèmes, facilitant le suivi, la communication et l'amélioration de la qualité.

Translated

Like
Saalim Quadri

AOSP Engineer @Vispero | LFX'23 | Linux Kernel | Android | Frameworks | Firmware | Platform
Report contribution
While working on a different codebase or your own project, try to create or work on top of issues present in the repository. Tag the issue in the commit description, to ensure a streamlined workflow and history.

Like

6 Share and publish your code using hosting platforms

A hosting platform is a service that hosts your code online and provides various features and functionalities to support your project. For example, some hosting platforms are GitHub, GitLab, Bitbucket, and SourceForge. Hosting platforms help you share and publish your code with others, and enable you to access, clone, fork, or pull your code from anywhere. They also offer other benefits, such as issue tracking, code review, continuous integration, documentation, licensing, and social networking.

Add your perspective

Saalim Quadri

AOSP Engineer @Vispero | LFX'23 | Linux Kernel | Android | Frameworks | Firmware | Platform
Report contribution
Publishing code on platforms makes it user friendly for ourselves and the community to track, review, publish, resolve one's codebase. Having package releases, code review workflow, issue tracking are one of the important aspects in open-source communities

Like

7 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?

Add your perspective

Saalim Quadri

AOSP Engineer @Vispero | LFX'23 | Linux Kernel | Android | Frameworks | Firmware | Platform
Report contribution
Linux Kernel development has helped me a lot in framing my commit messages as well as descriptions. There are strict guidelines given out by the community to follow, even before pushing a single patch on lore. Never forget to review patchset before pushing.

Like
David Wolfe

Building great teams, products, and customer experience.
Report contribution
Be sure to follow up with any updates to design docs, runbooks, UX updates (user facing documentation), and/or announcements regarding the changes and how they may impact end users, customer support or operational staff.

Like

How do you track and document changes and issues in open-source version control systems?

1

2

3

4

5

6

7

1 Choose a suitable VCS

2 Follow a consistent workflow

3 Write clear and descriptive commit messages

4 Use tags and branches to mark milestones and versions

5 Track and document issues using issue trackers

6 Share and publish your code using hosting platforms

7 Here’s what else to consider

Open Source Software

Rate this article

Thanks for your feedback

More articles on Open Source Software

More relevant reading