From a800d01375d989cefd56011467d26d51815ba2dc Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Wed, 13 Apr 2022 01:41:36 -0400 Subject: update docs --- QUICKSTART | 21 +++++++++++++++++++++ README | 47 +++++++++++++++++++++++++++++++++++------------ 2 files changed, 56 insertions(+), 12 deletions(-) create mode 100644 QUICKSTART diff --git a/QUICKSTART b/QUICKSTART new file mode 100644 index 0000000..47d7d52 --- /dev/null +++ b/QUICKSTART @@ -0,0 +1,21 @@ +See README for install instructions. Once you have +sbo-maintainer-tools installed: + +You can lint the build you're working on currently by running +"sbolint" while cd'ed into its directory. + +You can lint the *package* (if you've already built one) by running +"sbopkglint" in the build directory (and entering your password, if +you're asked for one). + +You can also lint any package by giving its filename as an argument +to sbopkglint. If you have a bunch of already-built packages, you can +lint them all at once with e.g. "sbopkglint /tmp/*.tgz". + +sbolint and sbopkglint each have extensive man pages and --help +output, which you'll want to read to learn to use the tools +effectively. + +You should also read the sbo-maintainer-tools README, if you haven't +already. In particular, the README tells you how to set up the git +hook (which is *very* handy, if you use git). diff --git a/README b/README index 7c06d83..ed255c2 100644 --- a/README +++ b/README @@ -2,32 +2,44 @@ sbo-maintainer-tools -------------------- These are "lint" tools to make life easier for SlackBuilds.org -maintainers and admins. +maintainers and admins. They check your builds and packages for +various problems, so your builds will be higher quality, and there +will be less work for the admins to do when reviewing your build for +approval. Included tools: - sbolint: checks your SlackBuild, README, .info file, and slack-desc. - Also there's a git pre-commit hook you should use, that automatically - calls sbolint and stops you from committing bad code. - sbopkglint: checks your package, after it's built. +- pre-commit-sbolint: a git pre-commit hook you should use, that + automatically calls sbolint and stops you from committing bad code. + Note that the SBo admins use these tools as part of the approval process, when you submit an update. Failure to pass the lint checks is a valid reason for rejecting your submission, so you should either make sure your scripts and packages pass the tests, or give a good explanation why a failure isn't relevant to your build (because the -tests aren't perfect, of course). +tests aren't perfect, of course, and there are exceptions to almost +every rule). Installation: -The best way to install sbo-maintainer-tools is to install them from -SBo (system/sbo-maintainer-tools). +The easiest way to install sbo-maintainer-tools is to install them +from SBo (system/sbo-maintainer-tools). The SBo build might be out +of date, so you might want to get the latest version from git and +install it manually: + + git clone https://slackware.uk/~urchlay/repos/sbo-maintainer-tools + cd sbo-maintainer-tools + make install # add PREFIX=/usr if you hate using /usr/local -If you prefer, you can install them with "make install" (defaults to -/usr/local; add 'PREFIX=/usr' if you'd rather). You can also run them -directly from the source directory, if you can think of a reason for -that (e.g. if you're hacking on the tests). +You can also run sbolint and sbopkglint directly from the source +directory (e.g. ./sbopkglint), if you can think of a reason for that +(maybe you're hacking on the tests). + +Git Hook: To use the git hook, copy pre-commit-sbolint to .git/hooks/pre-commit in your git work tree (wherever you cloned the SBo repository), @@ -36,5 +48,16 @@ pre-commit hook, you can copy/paste the code, or (possibly) just append pre-commit-sbolint to your existing hook (if it doesn't end with "exit 0"). -For more information, see the sbolint and sbopkglint man pages (or run -the scripts with --doc; it's the same thing). +If you absolutely must commit code that doesn't pass sbolint, you can +set SBOLINT=no in the environment, e.g. + + SBOLINT=no git commit -m'Message here' ... + +If you find yourself having to do this often, please contact the SBo +admins and explain the situation; it may mean sbolint needs updating. + +Documentation: + +For more information, see the sbolint and sbopkglint man pages (or +run the scripts with --doc; it's the same thing). There's also a +QUICKSTART file that gives the bare minimum info to get started. -- cgit v1.2.3