From cb5ef5e5aaecd0d9daddf4c06dba3cb5b6213152 Mon Sep 17 00:00:00 2001 From: Harald Hope Date: Sun, 30 Aug 2015 18:00:12 -0700 Subject: [PATCH] Added readme, to stave off any more absurd requests to tag rolling release software. --- README.txt | 308 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 308 insertions(+) create mode 100755 README.txt diff --git a/README.txt b/README.txt new file mode 100755 index 0000000..5cd73a3 --- /dev/null +++ b/README.txt @@ -0,0 +1,308 @@ +README for inxi - a command line system information tool + +===================================================================== +SUPPORT INFO: + +Do not ask for basic help that reading the inxi -h / --help menus, or +man page would show you, and do not ask for features to be added that +inxi already has. Also do not ask for support if your distro refuses to +update its inxi version, some are terrible about that. + +DOCUMENTATION: http://smxi.org/docs/inxi.htm +(smxi.org/docs/ is easier to remember, and is one click away from inxi.htm) +The one page wiki on github is only a pointer to the real resources. + +HTML MAN PAGE: http://smxi.org/docs/inxi-man.htm +INXI OPTIONS: http://smxi.org/docs/inxi-options.htm +NOTE: both options and man html versions may and probably will lag behind +current inxi because doing documentation is boring, and the man to html +converter I tried is really bad, so it's hard to update the man page html. + +ISSUES: https://github.com/smxi/inxi/issues +No issues accepted for non current inxi releases. See below for more on that. + +SUPPORT FORUMS: http://techpatterns.com/forums/forum-33.html +This is the best place to place support issues that may be complicated. + +If you are developer, use: +DEVELOPER FORUMS: http://techpatterns.com/forums/forum-32.html + +SOURCE VERSION CONTROL: https://github.com/smxi/inxi +MAIN BRANCH: master +DEVELOPMENT BRANCHES: one, two, three, android, bsd +Dev branches are rarely used, but that's where the really hard new features etc +are debugged and worked out. inxi itself has the built in feature to be able +to update itself from anywhere, including these branches, which is very useful +for development and debugging on many user systems. + +inxi was happily on googlecode until they decided to shut it down, which forced +me to pick an inferior option, github in this case. Since all the options were +bad, I picked the most popular of the bad options. I miss googlecode already... + +PULL REQUESTS: inxi is VERY complicated and VERY hard to work on, so unless +you have already talked to me about contributing, and, more important, shown +that you can actually work with this type of arcane code, please do not spend time +trying to work on inxi, unless it's a trivial patch, to the current branch, +current version. Please: NEVER even think about looking at or using previous +inxi commits, previous to the current one, as a base for a patch. If you do, +your patch / pull request will be rejected immediately, without any discussion. + +inxi has one and only one release, and that is the current one. All +previous releases are immediately obsolete on the commit of every new release. +There is no exception to this, and never will be. + +Man page updates, doc page updates, etc, of course, are easy and will probably +be accepted, as long as they are done according to the requirements. + +Read below re asking about tagging this rolling software release, short version: +don't ask. + +inxi releases early, and releases often, when under development. + +===================================================================== +ABOUT INXI - CORE COMMITMENT TO LONG TERM STABILITY + +inxi is a command line system information tool. It was forked from the ancient +and mindbendingly perverse yet ingenius infobash, by locsmif. inxi is lower case, +except when I create a text header here in a file like this, but it's always +lower case. + +The primary purpose of inxi is for support, and admin use. inxi is used +widely for forum and IRC support, which is I believe it's most common function. + +If you are piping output to paste or post, then make sure to turn off the +script colors with the -c 0 flag. Script colors in shell are characters. + +That was a buggy, impossible to update or maintain piece of software, so the +fork fixed those core issues, and made it flexible enough to expand and increase +the utility of. Which is what inxi has done. Locmsif has given his thumbs up +to inxi, so don't be fooled by legacy infobash stuff you may see out there. + +With some pain, inxi has gotten to the point where some of its hardware +tools are actually better, more accurate, and astoundingly, faster, than their +C version equivalents, but that's not because inxi is great, it's because +those other tools just aren't well done in my opinion. inxi should ALWAYS +show you your current system state, as far as possible, and should be more +reliable than your own beliefs about what is in your system, ideally. In +other words, the goal in inxi is to have it be right more than it is wrong +about any system that it runs on. And NEVER to rely on non current system +state data if at all possible. Some things, like memory/ram data, rely on +radically unreliable system self reporting based on OEM filling out data +correctly, which doesn't often happen, so in those cases, you want to +confirm things like ram capacity with a reputable hardware source, like +crucial.com, which has the best ram hardware tool I know of. + +Some might, correctly, note the insanity of writing a huge gawk program +wrapped in thousands of lines of bash, but this ignores the absolute core +mission of inxi: to always work on all systems all the time. Well, all +linux systems with the core tools inxi requires to operate installed. Ie, +not android, yet. What this means is this: you can have a 10 year old box, +or probably 15, not sure, and you can install today's inxi on it, and it +will run. It won't run fast, but it will run. I test inxi on a 200mghz +laptop from about 1998 to keep it honest. That's also what was used to +optimize the code. + +In other words, inxi will not fail on a bash/gawk update, and you can +generally count on Bash and Gawk being installed on any real GNU/Linux +system. Well, they should be, although for some perverse reason Ubuntu +refuses to include gawk, which is gnu awk, in their base install. Why gawk? +because that's the most commonly available language for parsing data and +creating reports. Arcane, yes, obsolete? yes, works? yes. Bash is interactive, +and is available on almost all GNU/Linux systems. Do I like Bash or Gawk? +No, I don't. But nothing comes close to the long term reliability and +stability of gawk/bash/sed/grep, nothing is even remotely close. I keep +looking, but language after language prove themselves to not be valid +candidates for this core stability requirement as they change or break their +APIs with new releases, along with not being parts of a generic core GNU/Linux +install. + +But why gawk instead of awk? That is an issue that has plagued inxi for a +long time, the bottom line is this: both bash and awk are such inferior +languages overall that the only way to really get them to work in a complex +scenario like inxi is to use the most advanced version of awk possible, which +is gnu awk, aka, gawk. Gawk has: case insensitive switches (critical for +parsing garbage random system data), gensub (search and replace like sed). + +This is why, for example, some Bash 4 things that would be nice to have in +inxi are not used, to not break backward compatibility. It is a show stopper +bug if an inxi update breaks something that was working in an old system. + +===================================================================== +BSD SUPPORT + +BSD support was, with great pain, added, though it's partial and incomplete. +BSDs are simply too hard to work with because of their extreme fragmentation, +ie, they don't even share one tool you take for granted on GNU/Linux, like +lspci. Nor do they share common methods of reporting system hardware data. +Nor does a single BSD, even within itself, like FreeBSD, even maintain standard +methods across releases. So the BSD support in inxi is basically what it is, +if more is wanted, then BSD people have to step up and do the work, always' +keeping in mind that all patches to inxi must not break existing functionality +for existing supported platforms, be they BSD or GNU/Linux. + +I like real BSDs, like OpenBSD, NetBSD, FreeBSD, etc, and prefer that the tools +in inxi that can be made to work on BSDs, do work, but their refusal to even use +the same tools or locations or syntaxes for system info simply makes it too +hard for me to do that work. I will always accept patches that are well done +however from competent people, if they do not break GNU/Linux, and extend BSD +support. Keep in mind, all patches must be based on tool/file tests, not BSD +version tests. inxi sets initial internal flags to identify that it is a BSD +system vs a GNU/Linux system, after that it tests for specific applications and +resources. + +Inxi will also start on Darwin, OSX's mutated version of a BSD, but my conclusion +about darwin is that it is Unix in name only, and I will not spend a second of my +time adding any further support for that crippled broken corporate pseudo-unix +system. Don't ask. + +If you want to run unix, then OSX is not unix, in my opinion. + +===================================================================== +INXI FEATURES AND FUNCTIONALITY + +Inxi's functionality continues to grow over time, but it's also important +to understand that each core new feature usually requires about 30 days work +to get it stable. So new features are not trivial things, nor is it acceptable +to submit a patch that works only on your personal system. One inxi feature +(-s, sensors data), took about 2 hours to get working in the alpha test on the +local dev system, but then to handle the massive chaos that is actual user +sensors output and system variations, it took several rewrites and about 30 +days to get somewhat reliable for about 98% or so of inxi users. So if your +patch is rejected, it's likely because you have not thought it through +adequately, have not done adequate testing cross system and platform, etc. + +===================================================================== +INXI RELEASE/SUPPORT/ISSUES/BUGS INFORMATION: + +Important: the only version of inxi that is supported is the latest current +master branch release. No issue reports or bug reports will be accepted for +anything other than current master branch. No merges, attempts to patch old code +from old releases, will be considered or accepted. If you are not updated to +the latest inxi, do not file a bug report since it's probably been fixed ages +ago. If your distro isn't packaging a current inxi, then file a bug report +with them, not here. The only valid working code base for inxi is the current +release of inxi. Distributions should never feel any advantage comes from using +old inxi releases because inxi has as a core promise to you, the end user, that +it will NEVER require new tools to operate. New tools may be required for a new +feature, but that will always be handled internally by inxi, and will not cause +any operational failures. This is a promise, and I will never as long as I run +this project violate that core inxi requirement. Old inxi is NOT more stable +than current inxi, it's just old, and lacking in bug fixes and features. + +inxi is a rolling release codebase, just like Debian Sid, Gentoo, or Arch +Linux are rolling release GNU/Linux distributions, with no 'release points'. + +Why this is apparently so difficult for some people to grasp is beyond me, +particularly with Debian, that has Sid, a rolling release, un-versioned, no +fixed release point, package pool. All my code is rolling release, some of +it just happens to roll more slowly than others. inxi moves slowly some months, +very rapidly others. When it's moving rapidly, it's often wise to wait for it +to slow down, but you don't have to. + +Your distro not updating inxi ever, then failing to show something that is +fixed in current inxi is not a bug, and please do not post it here. File +the issue with your distro, not here. Updating inxi in a package pool will +NEVER make anything break or fail, period. It has no version based +dependencies, just software, like gawk, sed, etc. There is never a valid +reason to not update inxi in a package pool of any distro in the world. + +Sys Admin type inxi users always get the first level of support. ie, convince +us you run real systems and networks, and your issue shoots to the top of +the line. As do any real bugs. Failure to supply requested debugger data +will lead to a distinct lack of interest on our part to help you with a +bug. ie, saying, oh, x doesn't work, doesn't cut it, unless it's obvious why. + +===================================================================== +TAGS - DO NOT ASK FOR INXI TO BE TAGGED!! + +In particular, no issue reports will be accepted relating to tagging inxi +releases. Why? Because tagging is a bad idea, that leads to insecure code +and packaging practices, and should not be recommended or used by package +maintainers. A packager should ALWAYS point to the actual commit they got +their code from, not a tag attached to that commit. For what should be +obvious reason, you can move tags, delete them, and point to bad code, +then good code, all without giving any indication at all that the tag or +its destination have been changed. In other words, relying on tagging to +identify code releases is identical to relying on fairy tales for security. +Point to the release commit ID, if you do, you will be pointing to the +code you downloaded for your package, if you do not, you won't be. + +Github makes that very easy: +https://github.com/smxi/inxi/tarball/[first 7 characters of commit id] + +This is a real link, to a real tarball, of a real commit. It's not a fiction, +a fantasy, a misleading and potentially serious security hole, like a tag. + +It's also easier to grab that than the somewhat cludgy git method to grab +a specific git commit id. Apparently with git 2.5, that cludgy method will +be replaced by a more basic thing, that corresponds to the svn way to grab +a commit, by commit number, cleanly. + +Further, tagging a rolling release code base is absurd, since every packager +is going to grab the current release of the codebase, unless they are very +confused or misguided (and the best way for me to encourage this type of +confusion and misguided action is by tagging any one release, thus suggesting +it is a static release). Thus I would have to tag every single commit since +I could never know when say, the Arch Linux maintainer is going to grab his +code, or any other distribution maintainer. Further, I would have to go back +and tag every past commit as well, since each and every one was and is, the +current release of inxi. That's without exception, no commit ever done trunk/ +master branch in inxi has ever not been the current release, by definition. + +I wouldn't waste time on noting something that should be obvious to anyone +with even a faint clue about code, or secure practices in terms of having a +real pointer to the code you grabbed, in other words not a tag! But I will +note it here to avoid being asked again about tagging. A tag is a post-it +sticky note, and should never be considered as a valid pointer, just a +convenience in some projects that works for some types of programming practices, +certainly not mine. + +All issue reports opened about tagging will be closed immediately (see issues +70/74 if you must, you won't get any different answer by repeating the same bad +logic again) without comment. File a distro bug report in your distro of choice +if they insist on asking for this bad idea, that's the right place to handle +the problem. + +===================================================================== + +INXI VERSION NUMBERING: + +inxi uses fairly classic version numbering, where the version numbers actually +mean something. + +The version number follows these guidelines: +Using example 2.2.28-6 + +The first digit(s), "2", is a major version, and almost never changes. Only +a huge milestone, or if inxi reaches 2.9.xx, when it will simply move up to +3.0.0 just to keep it clean, would cause a change. + +The second digit(s), "2", means a new real feature has been added. Not a +tweaked existing feature, an actual new feature, which usually also has a new +argument option letter attached. The second number goes from 0 to 9, and then +rolls over the first after 9. + +The third, "28", is for everything small, can cover bug fixes, tweaks to +existing features to add support for something, pretty much anything where you +want the end user to know that they are not up to date. The third goes from 0 +to 99, then rolls over the second. + +The fourth, "6", is extra information from Tarball maintainer, when either the +third digit has not changed, but there is a change or a patch comes out, +and the Tarball maintainer has time to pack the change. I don't usually use +this last one in master branch, but you will see it frequently in branch one, +two, etc development since that is used to confirm remote test system updates. + +The fourth number, when used, will be alpha-numeric, a common version would be, +in say, branch one: 2.2.28-b1-02, in other words, a branch 1 release, version 2. + +Inxi does not use the fiction of date based versioning because that imparts no +useful information to the end user, when you look at say, 2.2.28, and you last +had 2.2.11, you can know with some certainty that inxi has no major new features, +just fine tunings and bug fixes. And if you see one with 2.3.2, you will know +that there is a new feature, almost, but not always, linked to one or more new +line output items. Sometimes a fine tuning can be quite significant, like adding +wayland support to -G/-S, sometimes it's a one line code fix. + + +### EOF ###