diff --git a/CONTRIBUTING b/CONTRIBUTING index 267918b..72094c3 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 @@ -104,8 +111,13 @@ style guide for the usage text’s output format [0]. If committing a new utility, please include tests and documentation (see tests/ and docs/) for the new tool. -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' @@ -131,7 +143,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 diff --git a/README b/README index fdb05fb..0c01d5e 100644 --- a/README +++ b/README @@ -1,24 +1,28 @@ “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. +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. - -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 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. 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 @@ -43,7 +47,22 @@ 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 @@ -57,6 +76,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