The Digital Cat - Git

Punch 2.0.0 is out

2019-11-21T16:00:00+01:00

Punch 2.0.0 is out!

This is the latest release of the project that I started to replace bumpversion. Update your version while having a drink!

Punch is a configurable version updater, and you can use to automate the management of your project’s version number.

Changes:

DEPRECATION Punch doesn't support GLOBAL variables in the FILES variable anymore. The values given to fields in the FILES section are now simple strings and are not processed through Jinja2 anymore.
Initial drop of Python 2.x: the CI process doesn't test Python2.x anymore.
Complete review of documentation: the docs have been split in multiple files to make it easier to find information and to understand the program.
Initial implementation of automatic documentation from tests. Integration tests can now be parsed to extract examples for the documentation. See Examples from the tests
Named serializers: serializers now can be given a name through a dictionary syntax. With this change it becomes possible to select the serializer to use for the VCS. See Configuration > GLOBALS
Complex serializers: standard serializers use the same pattern both for the search and for the replace actions. With complex serializers you can define two different patterns, one for each action. See Advanced configuration > Complex serializers
The configuration of each file managed by Punch can override the global serializers or add new ones. See Configuration > FILES
Release notes: Punch can be configured to check if a pattern based on the new version is present in the managed files. This makes it simple to check if HISTORY files have been updated without requiring to interrupt the execution of the program and later restore it. See Advanced configuration > Release notes

Read the full documentation here

Punch - Update your version while having a drink

2016-05-31T16:00:00+01:00

So you completed your wonderful new project, all your test are successful (you test code, don't you?) and you just want to ship the new version and call it a day. Well, you just have to go and change the version number in your install script and save. Oh, right, you also have to open a feature branch, so that you may record the version update in your Git history. Well, easily done. Damn! You forgot to change the version number in the README.md file...

Managing the version number of a project is not easy. Not only you need to think about the versioning scheme and what part of the version to increase (see this post for some tips on this matter), but you also need to remember in which files you put the actual version number, and, depending on your workflow, to correctly manage the version control system commits.

Punch is a small tool that aims to simplify the latter parts, that is the management of the version number update process. Punch is a young project but the underlying structure should be flexible enough to allow the implementation of advanced usage cases that may arise in the future.

Features¶

Written in Python, but manages every kind of text file
May implement different versioning schemas
Currently supports integer version parts and multiple value integer parts
Version parts may be explicitly set to given values
The same version number can be represented in different ways using Jinja2 templates
Each managed file may override the global behaviour with custom settings
Can automatically commit using Git or git-flow
May optionally create annotated commits
Can simulate the version upgrade and show what is going to happen

Installation¶

You may install Punch in your virtual environment (or in your system) directly from PyPI

pip install punch.py

and you will have the punch executable available.

Useful links¶

Punch official documentation: https://punch.readthedocs.io/en/latest/
Official repository https://github.com/lgiordani/punch
Issues and pull requests https://github.com/lgiordani/punch/issues

Feel free to submit your issues or pull requests, contributions are welcome.

Using gitflow with GitHub: a simple procedure

2015-06-22T14:00:00+01:00

Git is a very powerful version control system and much of its power comes from its very simple basic structures. Git is mostly a manager of blob trees and even the most complex operations are basically tree operations.

The power of Git brings also a great flexibility, which means that Git doesn't dictate a specific workflow, leaving the programmer or the team to come up with a reasonable procedure.

Workflows¶

Two Git workflows are very widespread, for different reasons. The first is the GitHub model and the second is the gitflow one.

The GitHub model is widely used, because nowadays GitHub is the most used code management and collaboration website for open source projects. GitHub makes use of a workflow based on Pull Requests, and you can find some useful resources about it in the relative section at the end of the post.

Gitflow was proposed by Vincent Driessen in 2010 and quickly become one of the most used workflows, due to the fact that it covers most of the common needs of a developing team and is very easy to learn. Its workflow is based on different types of branches that are created when specific events occur in the team: a new feature has to be developed, a new release shall be published, a bugfix shall be quickly put in production, etc.

I personally find gitflow a very useful workflow and always use it even when I'm developing alone on a personal repository. It helps me to keep things in order and the beautiful set of tools named "gitflow AVH Edition" by Peter van der Does minimizes the number of operations I have to remember.

GitHub and gitflow¶

When working with GitHub, however, gitflow is not your best choice, mostly because of the big difference between the two ways of managing new features. GitHub wants you to put everything in a branch and submit a Pull Request, keeping the branch alive. The project maintainer then reviews the code and possibly merges your changes. At that point you are free to delete the branch and update your master.

Gitflow, on the other hand, usually makes you close features by merging into the special branch called develop, because is from that branch that you create releases (that are put into master). Closing a feature branch and merging the feature into develop is what does not work well with GitHub, since when you close the branch your Pull Request cannot be finalized.

Sure, you can leave a gitflow feature branch open, publish it, send your Pull Request and eventually delete it without closing the feature, but this way you are just partially using gitflow, not to mention the fact that this way some commands (such as git flow feature finish) become "dangerous", since they shall be avoided to preserve the GitHUb workflow integrity.

I will suggest here a procedure that allows to manage the local repository with gitflow, while hosting the remote repository on GitHub, without preventing to use gitflow features and GitHub Pull Requests.

The basic idea¶

The concept that allows to use both workflows is very simple: gitflow, when used locally to develop new features, makes use of the sole develop special branch. Every feature is created from that repository and eventually merged back there, so develop for a local repository becomes a sort of big feature branch.

Given this consideration we may create a local branch that tracks a remote one with the same name, and make it our GitHub feature branch, i.e. the branch that will be used to create a Pull Request. Locally, we create a Git symbolic reference to that branch and we call the reference develop, thus enabling the use of the gitflow workflow and tools.

When we finish adding features to the local feature branch (develop) we may squash the commits as usual and perform a forced push to the GitHub repository.

We may also maintain more than one GitHub feature branch, we just need to move the symbolic reference to the branch we want to work on. On every develop branch we may use gitflow features just like in a standard gitflow-enabled repository.

Releases¶

Obviously things change when we talk about releases. If the maintainer wants to use gitflow to create releases he or she needs to merge Pull Requests into their develop branch. This is not yet possible on GitHub web interface, but is already possible with command line Git. It however breaks a little the GitHub flow so I wouldn't suggest it at the moment. This feature has been already requested to the GitHub team (see this comment)

A simple procedure¶

To use the described procedure you just need to have a local repository with gitflow enabled, i.e. you need to have two branches master and develop, possibly with master tracking origin/master.

Then setup the repository issuing the following commands

$ # Move to the master branch
$ git checkout master
$
$ # Rename develop to _develop
$ git branch -m develop _develop 
$
$ # Create the feature branch
$ git checkout -b new_feature
$
$ # Push the feature branch to the remote (GitHub) and track it
$ git push -u origin new_feature
$
$ # Alias the feature branch with the name develop
$ git symbolic-ref refs/heads/develop refs/heads/new_feature

When you need to change your working feature branch just run

$ # Just change the target of the symbolic reference
$ git symbolic-ref refs/heads/develop refs/heads/other_feature

and if you need to go back to the original state execute the following commands

$ # Remove the symbolic reference
$ git symbolic-ref --delete refs/heads/develop
$
$ # Rename the original develop branch
$ git branch -m _develop develop

To squash commits into your feature branch and force push run these commands:

$ # Make sure we are dealing with our feature branch
$ git checkout new_feature
$
$ # Rebase on master (this is a develop, after all)
$ git rebase -i master
$
$ # Force a push on GitHub
$ git push origin +new_feature

The `gitflow gh` command¶

This repository is a fork of the official gitflow repository and inplements a new gitflow command gh to easily perform what has been described in this post. The changes are implemented in the github_support branch, which has been developed with the modified gitflow program itself.

As of 22-06-2015 I submitted a PR to the official gitflow repository, but I do not know if it is going to be accepted.

If you are interested in using this feature feel free to clone my gitflow repository and report any issue either there or in the PR itself. As soon as the PR is processed, I'll update this section.

The gh command is described in the README. It currently provides six commands: enable, disable, activate, import, squash and publish.

Links¶

The GitHUb workflow official documentation
The gitflow original post
The gitflow AVH Edition official repository
Some insights on Git objects
Another solution to work with GitHub and gitflow: HubFlow

Updates¶

2015-06-23: Added a section about a gitflow fork that implements the concepts explained in the post.

Feedback¶

The GitHub issues page is the best place to submit corrections.