From cd875df54797e2a71a7de2c426e2314cf58c027e Mon Sep 17 00:00:00 2001 From: DTB Date: Thu, 18 Jul 2024 09:32:58 -0600 Subject: [PATCH 1/3] README: attempt to clarify intent --- README | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/README b/README index fdb05fb..02e4c32 100644 --- a/README +++ b/README @@ -1,23 +1,29 @@ “Seek not to walk the path of the masters; seek what they sought.” – Matsuo Basho -The Bonsai harakit utilities are a replacement for standard POSIX utilities -which aim to fill its niche while expanding on their capabilities. These new -tools are the result of the careful examination of the current state of POSIX -and Unix utilies. The Unix Philosophy of “do one thing and do it well” are their -core but they avoid clinging to the past. +The Bonsai harakit is an alternative to the standard POSIX utility set that +aims to be simpler, easier, and more powerful than its counterpart. These tools +are the result of careful examination of the current state of POSIX and common +Unix utilities. They represent a vision of accomplishing everyday use cases +with tools that follow the Unix philosophy of “do one thing and do it well”, +without clinging to the past. The era of the original Unix tools has been long and fruitful, but they have their flaws. This project originated from frustrations with the way certain tools work and how other projects that extend POSIX don’t make anything better. -This project will not follow in the footsteps of GNU; extensions of POSIX will -not be found here. GNU extensions are a gateway to the misuse of the shell. The -harakit utilities will intentionally discourage use of the shell for purposes -beyond its scope. +The intent of harakit is not to conform to or extend POSIX, like the GNU or BSD +utilities, but to invent new utilities to perform the same tasks in more +intuitive ways. GNU and BSD extensions are convenient but often unhealthy, +forgetting the purposes of the tools they extend, or building into existing +utilities features that would be more useful as their own tools to be used +anywhere. Whereas other utility sets aim to provide a number of fully-featured +programs to be used individually, harakit tools are meant to be easily +composable and work together in pipelines. See docs/ for more on the specific utilities currently implemented. + Building Harakit utilities require a POSIX-compliant environment to compile, including a @@ -43,6 +49,7 @@ To remove all build and distributable files: $ make clean + Read More An Introduction to the Unix Shell @@ -57,6 +64,10 @@ Master Foo Discourses on the Unix-Nature Shell Programming! +UNIX Style, or cat -v Considered Harmful + + + -- Copyright © 2023–2024 Emma Tebibyte Copyright © 2024 DTB From d2f8fb8106313352434bbd3f2c193101e03d82a6 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 12 Aug 2024 17:53:43 -0600 Subject: [PATCH 2/3] README: improvements, community links --- README | 40 ++++++++++++++++++++++++++-------------- 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/README b/README index 02e4c32..0c01d5e 100644 --- a/README +++ b/README @@ -1,30 +1,28 @@ “Seek not to walk the path of the masters; seek what they sought.” – Matsuo Basho -The Bonsai harakit is an alternative to the standard POSIX utility set that -aims to be simpler, easier, and more powerful than its counterpart. These tools -are the result of careful examination of the current state of POSIX and common -Unix utilities. They represent a vision of accomplishing everyday use cases -with tools that follow the Unix philosophy of “do one thing and do it well”, -without clinging to the past. +Bonsai’s Harakit is an alternative to the standard POSIX utilities that aims to +be simpler, easier, and more powerful. These tools are the result of careful +examination of the current state common Unix utilities, POSIX-compliant and +otherwise, following frustrations with design decisions and implementation +details. They represent a vision of accomplishing everyday use cases with tools +that follow the Unix philosophy of “do one thing and do it well” without +clinging to the past. -The era of the original Unix tools has been long and fruitful, but they have -their flaws. This project originated from frustrations with the way certain -tools work and how other projects that extend POSIX don’t make anything better. - -The intent of harakit is not to conform to or extend POSIX, like the GNU or BSD -utilities, but to invent new utilities to perform the same tasks in more +The intent of Harakit is not to conform to or extend POSIX, like the GNU or BSD +utilities do, but to invent new utilities to perform the same tasks in more intuitive ways. GNU and BSD extensions are convenient but often unhealthy, forgetting the purposes of the tools they extend, or building into existing utilities features that would be more useful as their own tools to be used -anywhere. Whereas other utility sets aim to provide a number of fully-featured -programs to be used individually, harakit tools are meant to be easily +anywhere. Other utility sets aim to provide a number of fully-featured +programs to be used individually, Harakit utilities are meant to be easily composable and work together in pipelines. See docs/ for more on the specific utilities currently implemented. Building +======== Harakit utilities require a POSIX-compliant environment to compile, including a C compiler and preprocessor (cc(1) and cpp(1) by default), an edition 2023 Rust @@ -50,7 +48,21 @@ To remove all build and distributable files: $ make clean +Contributing +============ + +See the CONTRIBUTING file for contribution guidelines. + + +Community +========= + +xmpp://bonsai@covenant.murderu.us +irc://feeling.murderu.us/#bonsai + + Read More +========= An Introduction to the Unix Shell From e889159619b3537869dfecf5bdacbdd9efa73584 Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 30 Aug 2024 21:22:53 -0600 Subject: [PATCH 3/3] CONTRIBUTING: made better --- CONTRIBUTING | 44 +++++++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING b/CONTRIBUTING index 74e821e..03f78a7 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -1,26 +1,29 @@ Make sure to read our code of conduct in the CONDUCT file. -When contributing a pull request to the main branch, please sign your commits -with a PGP key and add your name and the year to the bottom of the list of -copyright holders for the file. For example, an existing copyright header might -read: + +Copyright Information +===================== + +When editing a file, create a copyright statement correlated to your +identity so that it is easier to keep track of who has touched what file. +Pseudonymous contributions are welcome (and encouraged). Place new copyright +information below existing copyright information. If there is an existing +copyright statement: * Copyright (c) 2022–2023 Emma Tebibyte -You would add your name below it like this: +you would add your name below it like this: * Copyright (c) 2022–2023 Emma Tebibyte * Copyright (c) 20XX Your Name -We accept contributions from people using aliases. - Only list years in which you modified the source file. For example: * Copyright (c) 2020–2021, 2023 Your Name This header shows that “Your Name” worked on this source file in 2020, 2021, and -2023. Please use the en dash (“–”) to separate the years in the copyright -notice. +2023. Please use the en dash (“–”, U+2013) to separate consecutive years in the +copyright notice. If you are contributing a new file, please prepend the following license header text to it, replacing the proper text on the copyright line: @@ -92,6 +95,10 @@ notice: * USE OR OTHER DEALINGS IN THE SOFTWARE. */ + +Style +===== + Make sure lines never exceed 80 columns in width when using four-character indentation steps. This helps contributors with smaller screens, those using side-by-side editor windows or panes, and those who have no text wrapping in @@ -99,12 +106,16 @@ their editor or terminal. For usage text and help messages, do not implement a -h option. Instead, print usage information when any erroneous option is specified. Follow the NetBSD -style guide for the usage text’s output format [1]. +style guide for the usage text’s output format [0]. -[1] -If committing a new source file, format the commit message following these -guidelines: +Committing +========== + +When contributing to Bonsai, please sign your commit with a PGP key and create +the commit with an identity which can be easily contacted. + +Format commit messages following these guidelines: $ git commit -m 'tool(1): add feature x' @@ -130,6 +141,13 @@ $ git commit -m 'tool(1): fix #42 & add feature x' Commit messages should be written in the present tense. + +References +========== + +[0] + + -- This work © 2023–2024 by Emma Tebibyte is licensed under CC BY-SA 4.0. To view a copy of this license, visit