This content originally appeared on Level Up Coding - Medium and was authored by Lucas de Brito Silva
How to automatically create a CHANGELOG and set commit and version standardization guidelines for your Python projects.
Summary
- Semantic versioning;
- Conventional Commits;
- Automatic Changelog Generator;
- Conclusion.
Semantic Versioning
Semantic versioning was a structure of rules created within the universe of software management, and this structure aims to control tags and avoid a problem called “dependency hell”, which prevents the release of new versions of a given application or study for dependency issues, something that grows along with the complexity of the projects.
In a nutshell, the proposed structure for mapping the tags is composed of X.Y.Z (Major.Minor.Patch), as in the image below, where changes that are no longer compatible with the previous version cause changes to MAJOR. Minor changes that add or change the current version, but are still compatible, increase the version of MINOR. Finally, the versions that are related only to bug fixes, these add to the PATCH value.
This structure was proposed by Tom Preston-Werner, co-founder of GitHub and creator of Gravatar, and by following the rules of semantic versioning, the developer gains benefits, such as mapped code, chronological control of changes, possibility of navigation between versions and dependencies management.
Conventional Commits
When thinking of a scientist or developer who already applies best practices related to versioning their code or study notebooks, it is worth setting aside a space to also communicate about the importance of commits for Git users, since commits are composed of the messages that carry the changes applied in the repositories, in order to contribute to the understanding of the changes. However, the tendency is that with the growth of the project, the commits become non-standard and the messages lose their true meaning, as in the image below.
At this point, we present the Conventional Commits with the proposal of being “A specification for adding human and machine readable meaning to commit messages”. This convention works by establishing a structure for commits, which can be demonstrated below.
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Basically, commits within the convention start using a type (which can be fix ,feat , build, chore, ci, docs, style, refactor, perf or test ) followed by the main message. The other parameters are optional.
So, to exemplify, some commits within the convention structure would be:
1) docs: correct spelling of CHANGELOG
2) feat(lang): add Polish language
3) fix: prevent racing of requests
Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.
Remove timeouts which were used to mitigate the racing issue but are obsolete now.
Reviewed-by: Z
Refs: #123
After adopting this structure, the Conventional Commits motto becomes real, bringing semantics to both the machines and those who benefit from the project.
Commitizen
A tool that helps in the adoption of Conventional Commits is Commitizen. Among the functions within this tool, it is mentioned that it formats the commit with a user interface, so it doesn’t need to memorize the default structure for commits.
After installing Python 3.6+ and Git 1.8.5.2+ as a prerequisite, the tool can be installed easily by using the following command in the terminal:
sudo pip3 install -U Commitizen (Linux)
brew install commitizen(macOS)
And its common use — to format the commits — can be performed by:
cz commit
The command above will demonstrate in the terminal some options to help format the commit, as in the image below.
Automatic Changelog Generator
After having standardized commits, as well as version control within the repository, it becomes possible to automate the creation and update of the CHANGELOG, which corresponds to a list containing the record of all changes made. The benefit of this list of changes is that with it there is a specific place to find the changes made in the project, being possible to present them to project leaders as well as all interested parties.
To carry out this automation, it will be necessary to use the commitzen tool, although there are other tools that can fulfill the same objective, such as the auto-changelog library.
The first step to take is to start the commitzen configuration files in the repository, which can be done by running the following command in the terminal:
cz init
After executing this command, a list of options to be selected in the terminal will be shown, so that a configuration of versions will be established. Feel free to use the image below as a configuration example and after placing all the parameters a pyproject.toml file will be inserted in the project so that the version control is established.
The next command to run in the terminal will be:
cz bump --files-only
This command will update the version of the project and assuming that the version control file has been created along with the walkthrough of this tutorial, the first version of the project will be established.
Finally, the next command will create a CHANGELOG.md file, so that it will contain all standardized commits and separated by commit type.
cz changelog
Conclusion
By establishing code standards, semantic versioning and conventional commits for the projects we work on, we raised the level of professionalism presented, so that we were able to evolve into automations that deliver value to all those interested in the project and this was proved with today’s article when we generate a changelog with few command lines. This can be implemented for both developers and data scientists, for both when applying these practices, it is possible to have a better organization of the project.
Automatic CHANGELOG with commit and version standardization in Python was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.
This content originally appeared on Level Up Coding - Medium and was authored by Lucas de Brito Silva
Lucas de Brito Silva | Sciencx (2022-06-20T11:36:00+00:00) Automatic CHANGELOG with commit and version standardization in Python. Retrieved from https://www.scien.cx/2022/06/20/automatic-changelog-with-commit-and-version-standardization-in-python/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.