101 stories
·
2 followers

Release notes: why and how?

2 Shares

Every free and open source project should probably make a release from time to time. Every release should be accompanied by release notes so that people interested in the software know what has changed, and what to expect from the new version.

Release notes can be massive enough to sub-projects of their own. This can be necessary for very large projects, such as Linux distributions. For projects more on the individual developer scale, release notes can be small and simple. My own preference is to include a file called NEWS (or NEWS.md) in the source tree, which lists the major, user-visible changes in each release. I structure mine as a reverse log file, pre-pending the newest release at the beginning. I don’t delete old releases, unless the file grows very big.

I am not fond of a “git commit log” as release notes. As a user I am really not interested in the meandering route by which the developers came to the new version. It may be possible to produce release notes by filtering strictly structured commit messages, but I’ve not seen it done well enough. Your experience may be different.

As a user, what I want to see in release notes are:

  • a list of new or changed features, with short descriptions of why I would want to use them
  • a list of fixed bugs, with short explanations of what the problem was so I know if I have been affected
  • a list of breaking changes, whether features or bug fixes, with some indication of what is needed to cope with the breakage, so I can make an informed decision of when and how to upgrade
  • anything else I as a user, system administrator, or packager need to know about, when upgrading

If I contribute to the project and want more detail, I’ll be happy to look at the actual version control history, with detailed commit messages and unified diffs of each change.

Examples from my projects:

  • Subplot
    • Subplot is tooling for documenting and verifying acceptance criteria in ways that all project stakeholders understand them
  • Obnam
    • Obnam is an encrypting backup program
  • vmdb2
    • vmdb2 builds virtual machine images with Debian installed
Read the whole story
brennen
25 days ago
reply
Boulder, CO
thcipriani
25 days ago
reply
Share this story
Delete

How to mirror the Russian Wikipedia with Debian and Kiwix

1 Share

It has been reported that the Russian government has threatened to block access to Wikipedia for documenting narratives that do not agree with the official position of the Russian government.

One of the anti-censorship strategies I've been working on is Kiwix, an offline Wikipedia reader (and plenty of other content too). Kiwix is free and open source software developed by a great community of people that I really enjoy working with.

With threats of censorship, traffic to Kiwix has increased fifty-fold, with users from Russia accounting for 40% of new downloads!

You can download copies of every language of Wikipedia for offline reading and distribution, as well as hosting your own read-only mirror, which I'm going to explain today.

Disclaimer: depending on where you live it may be illegal or get you in trouble with the authorities to rehost Wikipedia content, please be aware of your digital and physical safety before proceeding.

With that out of the way, let's get started. You'll need a Debian (or Ubuntu) server with at least 30GB of free disk space. You'll also want to have a webserver like Apache or nginx installed (I'll share the Apache config here).

First, we need to download the latest copy of the Russian Wikipedia.

$ wget 'https://download.kiwix.org/zim/wikipedia/wikipedia_ru_all_maxi_2022-03.zim'

If the download is interrupted or fails, you can use wget -c $url to resume it.

Next let's install kiwix-serve and try it out. If you're using Ubuntu, I strongly recommend enabling our Kiwix PPA first.

$ sudo apt update
$ sudo apt install kiwix-tools
$ kiwix-serve -p 3004 wikipedia_ru_all_maxi_2022-03.zim

At this point you should be able to visit http://yourserver.com:3004/ and see the Russian Wikipedia. Awesome! You can use any available port, I just picked 3004.

Now let's use systemd to daemonize it so it runs in the background. Create /etc/systemd/system/kiwix-ru-wp.service with the following:

[Unit]
Description=Kiwix Russian Wikipedia

[Service]
Type=simple
User=www-data
ExecStart=/usr/bin/kiwix-serve -p 3004 /path/to/wikipedia_ru_all_maxi_2022-03.zim
Restart=always

[Install]
WantedBy=multi-user.target

Now let's start it and enable it at boot:

$ sudo systemctl start kiwix-ru-wp
$ sudo systemctl enable kiwix-ru-wp

Since we want to expose this on the public internet, we should put it behind a more established webserver and configure HTTPS.

Here's the Apache httpd configuration I used:

<VirtualHost *:80>
        ServerName ru-wp.yourserver.com

        ServerAdmin webmaster@localhost
        DocumentRoot /var/www/html

        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined

        <Proxy *>
                Require all granted
        </Proxy>

        ProxyPass / http://127.0.0.1:3004/
        ProxyPassReverse / http://127.0.0.1:3004/
</VirtualHost>

Put that in /etc/apache2/sites-available/kiwix-ru-wp.conf and run:

$ sudo a2ensite kiwix-ru-wp
$ sudo systemctl reload apache2

Finally, I used certbot to enable HTTPS on that subdomain and redirect all HTTP traffic over to HTTPS. This is an interactive process that is well documented so I'm not going to go into it in detail.

You can see my mirror of the Russian Wikipedia, following these instructions, at https://ru-wp.legoktm.com/. Anyone is welcome to use it or distribute the link, though I am not committing to running it long-term.

This is certainly not a perfect anti-censorship solution, the copy of Wikipedia that Kiwix provides became out of date the moment it was created, and the setup described here will require you to manually update the service when the new copy is available next month.

Finally, if you have some extra bandwith, you can also help seed this as a torrent.

Read the whole story
thcipriani
48 days ago
reply
Share this story
Delete

Altering a Gerrit change (git workflow)

1 Share

I don’t use git-review for Gerrit interactions. This is primarily because back in 2012/2013 I couldn’t get git-review installed, and someone presented me with an alternative that worked. Years later I realized that this was actually the documented way of pushing changes to Gerrit.

As a little introduction to what this workflow looks, and a comparison with git-review I have created 2 overview posts altering a gerrit change on the Wikimedia gerrit install. I’m not trying to convince you, either way, is better, merely show the similarities/difference and what is happening behind the scenes.

Be sure to take a look at the other post “Altering a Gerrit change (git-review workflow)

I’ll be taking a change from the middle of last year, rebasing it, making a change, and pushing it back for review. Fundamentally the 2 approaches do the same thing, just one (git-review) requires an external tool.

1) Rebase

Firstly I’ll rebase the change by clicking the “Rebase” button in the top right of the UI. (But this step is entirely optional)

This will create a second patchset on the change, automatically rebase on the master branch if possible. (Or it would tell you to rebase locally).

2) Checkout

In order to checkout the change I’ll use the “Download” button on the right of the change near the changed files.

A dialogue will appear with a bunch of commands that I can copy depending on what I want to do.

As I want to alter the change in place, I’ll use the “Checkout” link.

This will fetch the ref/commit, and then check it out.

3) Change

I can now go ahead and make my change to the commit in my IDE.

The change is quite small and can be seen in the diff below.

Now I need to amend the commit that we fetched from gerrit.

If I want to change to commit message in some way I can do git commit --all --amend

If there is no need to change the commit message you can also pass the --no-edit option.

You’ll notice that we are still in a detached state, but that doesn’t matter too much, as the next step is pushing to gerrit, and once that has happened we don’t need to worry about this commit locally.

4) Push

In order to submit the altered commit back to gerrit, you can just run the following command

git push origin HEAD:refs/for/master

The response of the push will let you know what has happened, and you can find the URL back to the change here.

A third patchset now exists on the change on Gerrit.

Overview

The whole process looks like something like this.

Visualization created with https://git-school.github.io/
  1. A commit already exists on Gerrit that is currently up for review
  2. Clicking the rebase button will rebase this commit on top of the HEAD of the branch
  3. Fetching the commit will bring that commit on to your local machine, where you can now check it out
  4. Making a change and ammending the commit, will create a new commit locally
  5. You can then push this altered commit back to gerrit for review

If you want to know more about what Gerrit is doing, you can read the docs on the “gritty details”

Git aliases

You can use a couple of git aliases to avoid some of these slightly long commands

alias.amm=commit -a --amend alias.amn=commit -a --amend --no-edit alias.p=!f() { git push origin HEAD:refs/for/master; }; f

And you can level these up to provide you with a little more flexibility

alias.amm=commit -a --amend alias.amn=commit -a --amend --no-edit alias.main=!git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@' alias.p=!f() { git push origin HEAD:refs/for/$(git main)%ready; }; f alias.pd=!f() { git push origin HEAD:refs/for/$(git main)%wip; }; f
Code language: JavaScript (javascript)

You can read more about my git aliases in a previous post.

The post Altering a Gerrit change (git workflow) appeared first on addshore.

Read the whole story
thcipriani
62 days ago
reply
Share this story
Delete

Altering a Gerrit change (git-review workflow)

1 Share

I don’t use git-review for Gerrit interactions. This is primarily because back in 2012/2013 I couldn’t get git-review installed, and someone presented me with an alternative that worked. Years later I realized that this was actually the documented way of pushing changes to Gerrit.

As a little introduction to what this workflow looks, and a comparison with git-review I have created 2 overview posts altering a gerrit change on the Wikimedia gerrit install. I’m not trying to convince you, either way, is better, merely show the similarities/difference and what is happening behind the scenes.

Be sure to take a look at the other post “Altering a Gerrit change (git workflow)

One prerequisite of this workflow is that you have git-review installed and a .gitreview file in your repository!

I’ll be taking a change from the middle of last year, rebasing it, making a change, and pushing it back for review. Fundamentally the 2 approaches do the same thing, just one (git-review) requires an external tool.

1) Rebase

Firstly I’ll rebase the change by clicking the “Rebase” button in the top right of the UI. (But this step is entirely optional)

This will create a second patchset on the change, automatically rebase on the master branch if possible. (Or it would tell you to rebase locally).

2) Checkout

In order to checkout the change you need to grab the numeric change ID from the Gerrit UI (you can always find it in the URL).

Use this change ID with the -d flag of git-review, which stands for “download.

If you wanted to checkout a specific patchset of a change you can use the format 698261,3

git-review will fetch this change, and point a branch to the commit, using the format review/<AUTHOR>/<CHANGE-ID>

3) Change

I can now go ahead and make my change to the commit in my IDE.

The change is quite small and can be seen in the diff below.

Now I need to amend the commit that we fetched from gerrit.

If I want to change to commit message in some way I can do git commit --all --amend

If there is no need to change the commit message you can also pass the --no-edit option.

You’ll notice that we are still in a detached state, but that doesn’t matter too much, as the next step is pushing to gerrit, and once that has happened we don’t need to worry about this commit locally.

4) Push

You can then just run git review, with the -R flag if you want to avoid automatic rebasing of your changes.

A new patchset now exists on the change on Gerrit.

Overview

The whole process looks like something like this. (With git-review adding some extra branch names for changes locally)

Visualization created with https://git-school.github.io/
  1. A commit already exists on Gerrit that is currently up for review
  2. Clicking the rebase button will rebase this commit on top of the HEAD of the branch
  3. Downloading the change using git review -d will fetch the commit, and checkout a nammed branch with a HEAD at that commit
  4. Making a change and ammending the commit, will create a new commit locally, and on the same nammed branch
  5. You can then push this altered commit back to gerrit for review

If you want to know more about what Gerrit is doing, you can read the docs on the “gritty details”

Git aliases

You can use a couple of git aliases to avoid some of these slightly long commands

alias.amm=commit -a --amend alias.amn=commit -a --amend --no-edit

You can read more about my git aliases in a previous post.

The post Altering a Gerrit change (git-review workflow) appeared first on addshore.

Read the whole story
thcipriani
62 days ago
reply
Share this story
Delete

Monday, February 7, 2022 - paper again

2 Shares

Monday, February 7, 2022

paper again

What is it that paper has that the computer lacks?

The answer might be humility.

Paper doesn’t seek to consume and mediate all things — or at least the age in which it did so long ago fell to digital computers, databases, and networks between them.

Paper forms a part of the world computer, but in so many ways an almost forgotten part. Uncontested, or nearly so.

If it seemingly offers few features and little apparent leverage compared to software, then it also makes very few demands. It extracts little from the user’s autonomy and privacy, while remaining transferable, repurposable, cheap, generic, accessible. It’s not subject to platform degradation, malicious updates, DRM, new rents at vendor whim, or remote code execution vulnerabilities. There will probably never be a CVE issued for my favorite brand of paper, and I do not need to assume that three-letter agencies are automatically indexing its contents with the cooperation of its manufacturer.

What can be expressed on paper is vastly more constrained in many respects, but limited as it may be, it’s also open: To whatever can be expressed through ink, graphite, scissors, glue, binding, tape, staples, stitches, and filing. Paper can’t embed full motion video or execute complex instructions on my behalf, but neither are its possibilities bound by the hyper-elaborated techno-social systems that govern the display of media formats or the implementation of language runtimes.

There’s a line of thinking here that risks the kind of reductive rabbitholing on a tool fetish you so regularly get from people fixated on a process idea: People convinced that only plain text will serve as a format for any purpose. Zettelkasten devotees who will stringently insist that connecting notes remain grindingly manual. Angry holdouts lecturing mailing lists about the evils of HTML e-mail while the world conducts its business on Facebook and Slack. That sort of thing.

All the same, I think there’s something to it, just like there’s something vital that motivates a lot of hopeless impulses to digital minimalism and performative exercises in retrocomputing.

Here’s an age when the computer is the network and the network is a threat — simultaneously the only tool for thought and the thing that makes thought nearly impossible. It’s exhausting, enervating, periodically shattering. Its healthy effects are constantly overshadowed by its pathology. It’s owned by bad people and operated by a fundamentally compromised class of technocrats whose occasional glimmers of self-awareness can never overwhelm the home truth of who and what writes their paychecks.

Against this backdrop, other channels of thought can feel like an escape hatch, respite, a balm, a view of other paths that maybe aren’t entirely closed just yet. Opening a notebook, like going for a walk down by the river or messing around in a garden or sitting with friends around a campfire somewhere away from cell reception, can feel like sanity.

Of course paper is a technology, embedded in an industrial economy: And this, as usual, is to say that it is an ecological catastrophe. It consumes trees, soil, and landscapes. It poisons water and air, clogs transport networks and waste streams, facilitates consumption, and often assists in extending the control of computerized systems deep into the physical realm.

All the same, in the torrent of junk mail, grocery store fliers, BPA-coated thermal printer labels & receipts, redundant bills, bank notices, invoices, address change forms, fast food packages, and all the rest of it — well, the handful of notebooks and letters I spend in any given year feel comparatively benign.

(Drafted on paper.)

p1k3 / 2022 / 2 / 7

Read the whole story
thcipriani
101 days ago
reply
brennen
104 days ago
reply
Boulder, CO
Share this story
Delete

Stepping down as Testival Organizer

1 Share

I’m stepping down as a Testival organizer.

It all started in 2010. Davor Banović was organizing viaqa, a software testing conference in Osijek, Croatia. I think he had a few sponsors paying for the venue. But mostly Davor organized the conference with his own money.

At the time, I worked for a two person startup and the only other software tester I knew was Davor. I thought the conference would surely fail, since there would be just the two of us.

As far as I remember, to my huge surprise, about 50 people came to the conference. It was obvious that the market is ready for a software testing conference, something I was not expecting at all.

I was the main organizer of the viaqa conference in Zagreb, Croatia in 2011. Karlo Šmid helped me organize the conference. That event was when things started happening. Davor, Karlo and I became the core organizers of software testing meetups and conferences in Croatia. More people joined us over the years, but the three of us were the core.

After the 2011 viaqa conference Karlo organized Software Testers Speak Up Meeting. I think I was the one that suggested we should join the Software Testing Club (now the Ministry of Testing). So, from the second meetup we’ve changed the name to Zagreb Software Testing Club. I’ve joined Karlo in organizing Zagreb Software Testing Club and we’ve organized 25 meetups from 2011 to 2016.

Davor and I have visited several CITCON conferences and in 2014 the team has decided to help organize CITCON in Zagreb instead of the viaqa conference.

In 2015 we decided to rename the conference to Testival. I can’t remember who suggested the name, but everybody liked it. In 2016 we decided to rename our meetups from Software Testing Club to Testival, so both meetups and the conference were under the same name.

From 2015 to 2019 we have organized a conference every year, and most of the time we have a meetup every month.

In 2019 I decided to get serious about running. That took a lot of my time. Also, I had enough of organizing the Testival, so I’ve decided to step down as an organizer. I’ve announced that to the team. But then COVID happened and the Testival was put on hold anyway. We had a few online meetups in the last couple of years. I’ve helped organize them, so I didn’t really step down as an organizer. Then Karlo Šmid publicly stepped down and I’ve decided to do the same. Karlo wrote a blog post about it and I thought this was a great time to collect my thoughts and memories about Testival.

The Testival meetups and conferences were a success beyond all my expectations. We have organized a conference every year from 2010 to 2019. The meetups started in 2011. In the beginning they were every few months. In the last few years they were almost every month.

I hope Testival will revive after COVID. I’m looking forward to participating in meetups and conferences. The only change is that I don’t plan to be one of the organizers.

Read the whole story
thcipriani
109 days ago
reply
Share this story
Delete
Next Page of Stories