diff options
author | Unit 193 <unit193@ubuntu.com> | 2018-04-22 15:17:42 -0400 |
---|---|---|
committer | Unit 193 <unit193@ubuntu.com> | 2018-04-22 15:17:42 -0400 |
commit | 2f191c302fed4463b1192d2595184a65411adf25 (patch) | |
tree | bb9c1db12554ac8724f3b5850d0e780ab4309216 /README.txt | |
parent | e318468b98989bebe33f48b101115f9b7500b10a (diff) | |
download | inxi-2f191c302fed4463b1192d2595184a65411adf25.tar.bz2 inxi-2f191c302fed4463b1192d2595184a65411adf25.tar.xz inxi-2f191c302fed4463b1192d2595184a65411adf25.tar.zst |
New upstream version 3.0.07-1upstream/3.0.07-1
Diffstat (limited to 'README.txt')
-rw-r--r-- | README.txt | 376 |
1 files changed, 376 insertions, 0 deletions
diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..5443b0b --- /dev/null +++ b/README.txt @@ -0,0 +1,376 @@ +README for inxi - a command line system information tool + +The new Perl inxi is now here! File all issue reports with the master +branch. All support for versions prior to 3.0 is now ended, sorry. + +Make sure to update to the current inxi from the master branch before +filing any issue reports. The code in pre 2.9 versions literally no +longer exists in inxi 3. Bugs from earlier versions cannot be solved +in the new version since the pre 2.9 and the 2.9 and later versions +are completely different internally. + +inxi strives to support the widest range of operating systems and +hardware, from the most simple consumer desktops, to the most advanced +professional hardware and servers. + +The issues you post help maintain or expand that support, and are +always appreciated since user data and feedback is what keeps inxi +working and supporting the latest or not so latest hardware and +operating systems. + +See the BSD section below for qualifications re BSDs, and OSX in +particular. + +===================================================================== +MASTER BRANCH: + +This is the only supported branch, and the current latest commit is +the only supported 'release'. There are no 'releases' of inxi beyond +the current commit to master. All past commits are not supported. + +git clone https://github.com/smxi/inxi --branch master --single-branch + +OR direct fast and easy install: +wget -Nc https://github.com/smxi/inxi/raw/master/inxi + +OR easy to remember shortcut (which redirects to github): +wget -Nc https://smxi.org/inxi +wget -Nc smxi.org/inxi + +'Tagging' is purely a formality that certain distros can't figure out +how to do without, that's all. A tag is a pointer to a commit, and has +no further meaning. + +NOTE: Just because github calls tagged commits 'Releases' does not +mean they are releases! I can't change the words on the tag page. +They are tagged commmits, period. I did not want to use tags precisely +to avoid the idea that inxi has any release that exists that is other +than it's current master version, but I decided that it was less pain +to add tags than to argue this point any further. + +===================================================================== +DEVELOPMENT BRANCH: +All active development is now done on the inxi-perl branch (pinxi): + +git clone https://github.com/smxi/inxi --branch inxi-perl --single-branch + +OR direct fast and easy install: +wget -Nc https://github.com/smxi/inxi/raw/inxi-perl/pinxi + +OR easy to remember shortcut (which redirects to github): +wget -Nc https://smxi.org/pinxi +wget -Nc smxi.org/pinxi + +Once new features have been debugged, tested, and are stable, they +will move to the master branch. + +===================================================================== +LEGACY BRANCH: +If you'd like to look at or check out the Gawk/Bash version of inxi, +you can find it here, at the inxi-legacy branch (binxi): + +git clone https://github.com/smxi/inxi --branch inxi-legacy --single-branch + +OR direct fast and easy install: +wget -Nc https://github.com/smxi/inxi/raw/inxi-legacy/binxi + +OR easy to remember shortcut (which redirects to github): +wget -Nc https://smxi.org/binxi + +This version will not be maintained, and it's unlikely that any time +will be spent on it in the future, but it is there in case it's of +use or interest to anyone. + +===================================================================== +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 won't +update its inxi version, some are bad about that. + +DOCUMENTATION: https://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. + +https://github.com/smxi/inxi/tree/inxi-perl/docs +Contains specific Perl inxi documentation, of interest mostly to +developers. Includes internal inxi tools, values, configuration items. +Also has useful information about Perl version support, including the +list of Core modules that _should_ be included in a distribution's +core modules, but which are unfortunately sometimes removed. + +HTML MAN PAGE: https://smxi.org/docs/inxi-man.htm +INXI OPTIONS PAGE: http://smxi.org/docs/inxi-options.htm +NOTE: These may not always be up to date, but generally track the most +recent inxi commits. + +ISSUES: https://github.com/smxi/inxi/issues +No issues accepted for non current inxi releases. See below for more on +that. Unfortunately as of 2.9, no support or issues can be accepted for +older inxi's because inxi 2.9 (Perl) and newer is a full rewrite, and +legacy inxi is not being supported since our time here on earth is +finite (plus of course, one reason for the rewrite was to never have +to work with Gawk->Bash again!). + +SUPPORT FORUMS: https://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: https://techpatterns.com/forums/forum-32.html + +SOURCE VERSION CONTROL: https://github.com/smxi/inxi +MAIN BRANCH: master +DEVELOPMENT BRANCHES: inxi-perl, one, two +inxi-perl is the dev branch, the others are rarely if ever used. 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 various user systems. + +PULL REQUESTS: Please talk to me before starting to work on patches of +any reasonable complexity. inxi is hard to work on, and you have to +understand how it works before submitting patches, unless it's a trivial +bug fix. Please: NEVER even think about looking at or using previous +inxi commits, previous to the current master version, as a base for a +patch. If you do, your patch / pull request will probably be rejected. +Developers, get your version from the inxi-perl branch, pinxi, otherwise +you may not be current to actual development versions. inxi-perl pinxi +is always equal to or ahead of master branch inxi. + +Man page updates, doc page updates, etc, of course, are easy and will +probably be accepted, as long as they are properly formatted and +logically coherent. + +inxi releases early, and releases often, when under development. + +PACKAGERS: inxi has one and only one 'release', and that is the current +commit to master branch (plus pinxi inxi-perl branch, of course, but +those should never be packaged). + +===================================================================== +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. + +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 the utility of the original ideas. Locmsif has given his thumbs +up to inxi, so don't be fooled by legacy infobash stuff you may see +out there. + +inxi is lower case, except when I create a text header here in a file +like this, but it's always lower case. Sometimes to follow convention +I will use upper case inxi to start a sentence, but i find it a bad +idea since invariably, someone will repeat that and type it in as the +command name, then someone will copy that, and complain that the +command: Inxi doesn't exist... + +The primary purpose of inxi is for support, and sys 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 (or writing to file), inxi +now automatically turns off color codes, so the old suggestion to +use -c 0 to turn off colors is no longer required. + +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 not 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. + +The core mission of inxi is to always work on all systems all the +time. Well, all 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 200 MHz laptop from about 1998 to keep it +honest. That's also what was used to optimize the code at some +points, since differences appear as seconds, not 10ths or 100ths +of seconds on old systems like that. + +inxi is being written, and tested, on Perl as old as 5.08, and will +work on any system that runs Perl 5.08 or later. Pre 2.9.0 Gawk/Bash +inxi will also run on any system no matter how old, within reason, +so there should be no difference. + +===================================================================== +BSD SUPPORT + +Real BSDs: +BSD support is not as complete as GNU/Linux support due to the fact +some of the data simply is not available, or is structured in a way +that makes it unique to each BSD. This fragmentation makes supporting +BSDs far more difficult than it should be in the 21st century. The +BSD support in inxi is an ongoing process, with more features being +added as new data sources and types are discovered. + +All BSD issue reports unless trivial and obvious will require 1 of +two things: + +1. a full --debug 21 data dump so I don't have to spend days trying +to get the information I need to resolve the issue file by painful +file from the issue poster. This is only the start of the process, +and realistically requires 2. to complete it. + +2. direct SSH access to at least a comparable live BSD version/system, +that is, if the issue is on a laptop, access has to be granted to the +laptop, or a similar one. + +Option 2 is far preferred because in terms of my finite time on this +planet of ours, the fact is, if I don't have direct (or SSH) access, +I can't get much done, and the little I can get done will take 10 to +1000x longer than it should. That's my time spent (and sadly, with +BSDs, largely lost), not yours. + +I decided I have to adopt this much more strict policy with BSDs +after wasting untold hours on trying to get good BSD support, only +to see that support break a few years down the road as the data inxi +relied in changed structure or syntax, or the tools changed, or +whatever else makes the BSDs such a challenge to support. In the end, +I realized, the only BSDs that are well supported are ones that I have +had direct access to for debugging and testing. + +I will always accept patches that are well done, if they do not break +GNU/Linux, and extend BSD support, or add new BSD features, and follow +the internal inxi logic, and aren't too long. inxi sets initial internal +flags to identify that it is a BSD system vs a GNU/Linux system, and +preloads some data structures for BSD use, so make sure you understand +what inxi is doing before you get into it. + +OSX: +Do not insult real BSDs by calling OSX a BSD. OSX is the least +Unix-like operating system I've ever seen that claims to be a Unix, +its tools are mutated, it's data randomly and non-standardly organized, +and it totally fails to respect the 'spirit' of Unix, even though it +might pass some random tests that certify a system as a 'Unix'. + +If you want me to use my time on OSX features or issues, you have to +pay me, because Apple is all about money, not freedom (that's what +the 'free' in 'free software' is referring to, not cost), and I'm not +donating my finite time in support of non-free operating systems. + +===================================================================== +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 run. 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. For pre 2.9 releases, it's +also significantly slower, and with fewer 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'. + +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 Perl 5.xx, lspci, etc. +There is never a valid reason to not update inxi in a package pool of +any distro in the world (with one single known exception, the Slackware +based Puppy Linux release, which ships without the full Perl language. +The Debian based one works fine). + +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. + +===================================================================== + +INXI VERSION NUMBERING: + +inxi uses 'semantic' version numbering, where the version numbers +actually mean something. + +The version number follows these guidelines: +Using example 3.2.28-6 + +The first digit(s), "3", is a major version, and almost never changes. +Only a huge milestone, or if inxi reaches 3.9.xx, when it will simply +move up to 4.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. It could also be +adding a very complicated expansion of existing features, like Wayland. +It depends. + +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 about certain types of inxi +updates. I don't usually use this last one in master branch, but you +will see it in branches one,two, inxi-perl, inxi-legacy since that is +used to confirm remote test system patch version 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. + +In the past, now and then the 4th, or 'patch', number, was used in +trunk/master branches of inxi, but I've pretty much stopped doing that +because it's confusing. + +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, sometimes it's a +one line code fix. + +A move to a new full version number, like the rewrite of inxi to Perl, +would reflect in first version say, 2.9.01, then after a period of +testing, where most little glitches are fixed, a move to 3.0.0. These +almost never happen. I do not expect for example version 4.0 to ever +happen after the 3.0 release of early 2018, unless so many new +features are added that it actually hits 3.9, then it would roll +over to 4. + +### EOF ### |