Developing GParted using Git
- How to build GParted using git
- How to create your first GParted patch using git
- Verifying every change of a patch set compiles
- Suggested References
How to build GParted using git
Be sure to install the dependencies for GParted.
These are described in the "Building from source" portion of the README file.
Checkout a copy of the source code from the git repository:
git clone https://gitlab.gnome.org/GNOME/gparted.git
Compile the GParted source code into an executable:
cd gparted ./autogen.sh make
Install the GParted executable (as root):
How to create your first GParted patch using git
- Clone the git repository locally:
git clone https://gitlab.gnome.org/GNOME/gparted.git
- Set your name and email address:
git config --global user.name "Joe Bloggs" git config --global user.email "email@example.com"
- Create a new branch and switch to it:
cd gparted git checkout -b feature
- Edit the code, compile and test it.
# Use favourite editor ./autogen.sh make su root -c src/gpartedbin
- Commit change to git:
git add file1 file2 ... git commitCompose a suitable commit message:
Short one line summary of change (#999999)
Optional longer description explaining why the change is necessary.
Include details that will help the reviewer understand how the code
is broken and being fixed or why this change is an improvement.
Bug #999999 - GNOME Bugzilla one line summary
- Long lines should be wrapped at 72 characters, including quoted text and document fragments.
- Quoted command line output should not be wrapped.
- When including GParted commit IDs just include SHA1 value.
(gitk and CGit on https://git.gnome.org/ convert them into local clickable links).
- When quoting a commit ID of another package use the full Git web URL so that, at least to humans, it is clear it is a foreign commit ID. (gitk and cgit still make just the SHA1 clickable to a non-existent local commit though).
TIP: Improve Patch Readability
Make large and complicated changes as a series of smaller changes by repeating steps 4 and 5 as necessary. Note that each incremental patch should compile and run properly.
- Create a patch file:
git format-patch master -n --stdout > ~/mypatch.mbox
- Final review, apply, compile and test:
cd /tmp git clone https://gitlab.gnome.org/GNOME/gparted.git gparted-test cd gparted-test git am ~/mypatch.mbox ./autogen.sh make su root -c src/gpartedbin
TIP: Ensure patch applies cleanly
When applying the patch, make sure it applies cleanly. For example there should be no messages appearing such as trailing whitespace.
See Bug 696471 - Fix trailing whitespace errors for a discussion of why we only fix existing trailing whitespace in GParted patch-by-patch, and for ideas on how to avoid trailing whitespace.
- Attach ~/mypatch.mbox to your GNOME bug report with a few words.
Verifying every change of a patch set compiles
NOTE: Ensuring that every change in a multi patch set compiles is important for incremental testability and enabling the use of git bisect in searching for the commit which introduced a bug.
- One time set-up of
mkdir -p ~/bin cd ~/bin wget https://raw.github.com/dustin/bindir/master/git-test-sequence chmod 755 git-test-sequence wget https://git.gnome.org/browse/gparted/plain/testbuild.sh chmod 755 testbuild.sh
- Clone GParted for testing:
cd /tmp git clone https://gitlab.gnome.org/GNOME/gparted.git gparted-test cd gparted-test
- Apply and test build every patch in the set:
git am ~/review-patchset.mbox git-test-sequence origin/master.. testbuild.sh
testbuild.sh is for developers to build GParted in a git repository, appending the top commit and build results to the log file testbuild.log. It is intended for use with git-test-sequence to verify every commit in a patch set compiles, but it can be used standalone too.
Build current code:
rm testbuild.log testbuild.sh echo $? less testbuild.log
Parameters on the command line are passed to autogen.sh, which in turn are passed on to configure. See the INSTALL file for details on parameters to configure. Example:
By default testbuild.sh instructs make to use the number of processors in the machine as the number of jobs to run simultaneously. This is to minimise build time. This can be overridden by specifying the required parameters to make in the MAKEFLAGS environment variable. See make(1) for details of parameters to make. Example:
MAKEFLAGS='-j 2 -w' testbuild.sh
Build current code specifying both alternative make flags and configure parameters:
rm testbuild.log MAKEFLAGS='-j 2 -w' testbuild.sh --prefix=/usr echo $? less testbuild.log
git-test-sequence (blog: git test-sequence: Push Working Changes) allows a sequence of git commits to be tested. The range of commits is specified using standard git commit ranges syntax (about 2/3 down the page). Combined with testbuild.sh it allows us to verify every change of a patch set compiles.
Git-test-sequence records test results in the local git repository object store allowing it to report immediately when passed tests are re-run again.
git-test-sequence <commit_range> <test_program>
Normal case would be to apply patch set for review and test build all commits between upstream master and current head:
cd /tmp git clone git://git.gnome.org/gparted gparted-test cd gparted-test git am ~/review-patchset.mbox git-test-sequence origin/master.. testbuild.sh
Test build a range of commits while also specifying parameters to configure and alternative make flags:
cd /tmp git clone git://git.gnome.org/gparted gparted-test cd gparted-test MAKEFLAGS='-j 2 -w' git-test-sequence GPARTED_0_14_1..GPARTED_0_15_0 'testbuild.sh --prefix=/usr'
On failure examine the log file testbuild.log for details.