Suggestions to improve packaging of mgitstatus

[lyknode]

Hi @fboender,

First and foremost, thank you for mgitstatus. This tool saved me countless times from writing a quick and dirty for loop in bash, while having a nice output and expected options.

To share the awesomeness of this tool, I intend to package it for Debian. It should be available in the next stable release for users to install with apt install mgitstatus.

As such, I would like to suggest a couple of changes that could improve the easiness of packaging of mgitstatus. I'm happy to provide you with the corresponding PRs but I would like to discuss each point with you first.

Suggestions

1. Build system

I'd suggest to use a Makefile for the build system. Easy to use, and fairly easy to maintain for a small project, it would allow users to test and install with:

make #for the manpage
make test #for shellcheck
sudo make install

With the combination of DESTDIR and PREFIX, it would install by default in /usr/local and allow packaging tools to install in the correct tree.

This would replace build.sla and install.sh

2. Generated files

In Debian, generated files are quite tricky to deal within the source. The simple explanation is that if one cannot reproduce the file bit by bit from the source, it means that the generated files has no source and therefor is not open source.

The issue in mgitstatus is for the manpage mgitstatus.1. That file is obviously generated from mgitstatus.1.md but depending on the system you generate it from, the output will change (for instance, just from the pandoc version).

To deal with that, mgitstatus.1 would need to be removed and generated, at build time, by users (using make).

Now, I know that this suggestion can put off some maintainers due to the additional build dependency (here, pandoc), so I don't have my hopes up. We have ways to deal with that in Debian so it's really up to you whether you want to address this issue or not.

3. Release authentication

I would suggest to make available a cryptographic signature (using GPG keys) of your release tarball. By publishing the signature along side the source tarballs, you ensure that any modification by a third party will be detected by end-users.

---

All of those are suggestions, and as I've said, I'll be happy to provide PRs if
you are interested by those evolution.

If you have any questions regarding the packaging of mgitstatus for Debian do not hesitate to ask.

Looking forward to your comments,

[fboender]

Hey lyknode!

To share the awesomeness of this tool, I intend to package it for Debian.

Ah, that's fantastic! Thank you so much for your effort.

I'd suggest to use a Makefile for the build system

I personally really dislike Makefiles, but I understand that's it's much more standard. Given that this is such a small project, I can totally live with getting rid of the build.sla and install.sh files and replacing them with a single Makefile. I'd appreciate a pull request for this, as I always run into problems trying to write them ;-)

To deal with that, mgitstatus.1 would need to be removed and generated, at build time, by users (using make).

I used to write my manpages directly in Troff. The pandoc solution is just a slightly more convenient method for me. If that interferes, I suggest I just port the manpage to plain old Troff, and we put that in the repo as is. We can then completely get rid of the dependency on Pandoc. Is that an idea?

I would suggest to make available a cryptographic signature (using GPG keys) of your release tarball.

That would basically be just generating the release tarball and then generating a detached signature with my private key and uploading both files? I'm going to have to give this some more thought. A release right now is just a press of a button in Github. I want to keep the overhead here as low as possible. Would it add a lot to the security of the project? Right now the only official place to get releases is from the Github releases page, which is already tied to my account.

[SuperSandro2000]

The simple explanation is that if one cannot reproduce the file bit by bit from the source, it means that the generated files has no source and therefor is not open source.

That's not true. If it isn't the same bit by bit it isn't reproduceable but still open source.

I would suggest to make available a cryptographic signature (using GPG keys) of your release tarball. By publishing the signature along side the source tarballs, you ensure that any modification by a third party will be detected by end-users.

This are just the auto generated tar balls by github. A lot of other packages don't have signed archives either and they where accepted. Also the current state of gpg is not recommendable to anyone not tech savy.

I used to write my manpages directly in Troff. The pandoc solution is just a slightly more convenient method for me. If that interferes, I suggest I just port the manpage to plain old Troff, and we put that in the repo as is. We can then completely get rid of the dependency on Pandoc. Is that an idea?

That should work.

[SuperSandro2000]

I created #41 which adds a Makefile that represents the current scripts.

If you need help updating it to troff or have any other questions please reach out to me.

[lyknode]

@fboender,

To deal with that, mgitstatus.1 would need to be removed and generated, at build time, by users (using make).

I used to write my manpages directly in Troff. The pandoc solution is just a slightly more convenient method for me. If that interferes, I suggest I just port the manpage to plain old Troff, and we put that in the repo as is. We can then completely get rid of the dependency on Pandoc. Is that an idea?

It definitely is a possibility but I would take into account the fact that markdown is way easier for people to read and contribute to as opposed to the Troff format.

Given that pandoc is only a build dependency and final user will not need it, I'd say it fine to keep it and only have the markdown version in the sources.

I would suggest to make available a cryptographic signature (using GPG keys) of your release tarball.

That would basically be just generating the release tarball and then generating a detached signature with my private key and uploading both files? I'm going to have to give this some more thought. A release right now is just a press of a button in Github. I want to keep the overhead here as low as possible. Would it add a lot to the security of the project? Right now the only official place to get releases is from the Github releases page, which is already tied to my account.

Yes, that consist in adding a detached signature of the tarballs next to them.

Well, there have been cases of malicious code added to the release in the opensource community. I can recall at least phpmyadmin where one of sourceforge mirror got compromised (adding a nasty eval $_POST...). I'm not aware of any breach or corruption on github but no system/platform is perfect. So does the risk exists? yes. Is it likely to happen to a small project like mgitstatus? no.

That being said, it looks like you already own a GPG key and creating the signature is one command away :) It's up to you.

@SuperSandro2000,

The simple explanation is that if one cannot reproduce the file bit by bit from the source, it means that the generated files has no source and therefor is not open source.

That's not true. If it isn't the same bit by bit it isn't reproduceable but still open source.

That actually depends on the context, when building, yes, generated files can be unreproducible but still be open-source (because you generated from the source), but when distributing the source it's actually another matter. How can you be sure that a file comes from an available source if you can't build it yourself. I totally agree that in the case of mgitstatus, this is technicalities but it already been discussed in Debian and generally package maintainers just get rid of the generated files to avoid the package being rejected.

I would suggest to make available a cryptographic signature (using GPG keys) of your release tarball. By publishing the signature along side the source tarballs, you ensure that any modification by a third party will be detected by end-users.

This are just the auto generated tar balls by github. A lot of other packages don't have signed archives either and they where accepted. Also the current state of gpg is not recommendable to anyone not tech savy.

That is true, packages doesn't get rejected for that reason. It's just a nice to have additional security. Especially since distributions ensure that packages (or they metadata) are signed, it's even better is the trust chain can go up to the upstream sources.

[fboender]

@lyknode

Given that pandoc is only a build dependency and final user will not need it, I'd say it fine to keep it and only have the markdown version in the sources.

Then I'd prefer to keep the Markdown version. Mostly because it can be read straight from Github's UI.

That being said, it looks like you already own a GPG key and creating the signature is one command away :) It's up to you

The benefits outweigh the effort in this case, so I'll set something up in the near future. I do have to check my key hygiene a bit. I'm 100% certain I've never leaked my priv key, but should probably do something with subkeys or something.

it's even better is the trust chain can go up to the upstream sources.

Agreed.

@SuperSandro2000

I created #41 which adds a Makefile that represents the current scripts.

Nice, thanks! If you could add the .PHONY tag and update the merge request, I'll merge it asap.

[lyknode]

FYI, mgitstatus has just been accepted into debian today.

https://tracker.debian.org/pkg/mgitstatus

From Debian 11 (bullseye) and forward, people will be able to:

apt install mgitstatus