search

AppImage / docs.appimage.org

Source code of AppImage project's documentation
https://docs.appimage.org/
Other
42 stars 42 forks source link

Fast links to copy-and-paste snippets #29

Open probonopd opened 5 years ago

probonopd commented 5 years ago

https://twitter.com/freakboy3742/status/1160385448012763136

My litmus test is can I copy-paste steps and have a working build in less than 10 lines of script/code. New user/on boarding experience is so critical.

probonopd commented 5 years ago

Links to things like https://github.com/probonopd/linuxdeployqt/#using-linuxdeployqt-with-travis-ci

TheAssassin commented 5 years ago

I am not going to reiterate here why this is mostly a bad idea, at least/especially with Travis CI scripts. I can't repeat myself often enough that there are ready-to-use, copy-paste snippets in the docs already, can I?

For the average developer running something local is important and also ensures portability and independence from CI platforms. You don't want to bind yourself too much to proprietary infrastructure.

You can copy bash scripts doing all you need in https://docs.appimage.org/packaging-guide/from-source/native-binaries.html#examples, these also elaborately explain what they do in every step. That's not as cryptic as an uninspired Travis CI yml thingy that encourages people to bind themselves to proprietary services and don't explain e.g., why tools need to be run twice, etc. The scripts have been written with great care, and there's even a snippet that shows how to run them from Travis, https://docs.appimage.org/packaging-guide/from-source/native-binaries.html#travis-ci.

My mantra is that I don't want to hand out weird scripts which people cannot maintain themselves because they don't understand them. Also, people who show no intent in understanding them will just come back to me and expect me to fix their issues. That binds a lot of time and is no fun at all. Therefore my idea is to give them resources they can copy-paste if they don't want to invest 5 minutes into reading the docs, but at least then have some starting points to debug their issues. Also, I can run these scripts myself if I should decide to help with starting problems on my own computer, and don't have to wait for something like Travis that takes ages to build something and also is impossible to debug runtime failures on.

Your linuxdeployqt script there suffers from so many of the issues I just mentioned, hence sharing it with anyone is not just a bad idea for sustainability reasons (i.e., having them maintain it; they'd rather remove it if they lose interest), but also gets you into a situation where everyone will just come to you to fix issues that are easy enough to solve by themselves, e.g., wrong paths.

I haven't had a single linuxdeploy user complaining about not being able to resolve an issue unless there was a bug. And even that happens only every couple months.

probonopd commented 5 years ago

I can't repeat myself often enough that there are ready-to-use, copy-paste snippets in the docs already, can I?

Apparently @freakboy3742 did not find them, just like me. They are not the first thing you see. Also, it's spead out across more than one file, so it's two copy-and-pastes rather than one.

My mantra is that I don't want to hand out weird scripts which people cannot maintain themselves because they don't understand them

While I respect your opinion, the optimal "script" imho would be a one-liner where there is no need to understand anything for an AppImage developer who is running that one-liner. (We both know that we are not there yet, but at least that's where I'd like to go.)

TheAssassin commented 5 years ago

It just doesn't make so much sense to insist on a magic auto command that does everything right. Making things too easy to people often ends up in catastrophic failure, in software distribution at least. There's so many magic automations that people nowadays have no sense about licenses, dependency management etc., which is IMO pretty bad.

In terms of build systems, there can't be a one liner either, since there's things like building out of source that require a little effort to set up. My scripts do that for instance.

Making random broken AppImages may be simple. Making good ones that are also legally correct etc. requires effort from a develooper. Any reason for me to document is to provide developers with knowledge to deal with these questions. That may sound off-putting, but that's a philosophy I don't intend to give up on. It makes no sense to me to ignore these questions. If I look over GitHub, aside from tons of proprietary projects (lacking a license file entirely) there's so many which just do it wrong or violate other people's copyright (even with the best intentions, it's not just morally bad but also has legal implications)...