From 05d38453457df03db8f2a7d3ac2bfd955ff3fba9 Mon Sep 17 00:00:00 2001 From: Psionik K <73710933+psionic-k@users.noreply.github.com> Date: Fri, 16 Dec 2022 06:45:43 -0600 Subject: [PATCH] readme proofread & verbeage Signed-off-by: Psionik K <73710933+psionic-k@users.noreply.github.com> --- README.org | 109 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 67 insertions(+), 42 deletions(-) diff --git a/README.org b/README.org index 711894c..ed97fe6 100644 --- a/README.org +++ b/README.org @@ -8,14 +8,17 @@ #+HTML: CI workflow status #+HTML: DCO Check +This repository is a kit to start a new elisp package repository. The package +contained has commands to streamline elisp development. + * Quickly set up an Emacs Lisp repository on Github with: - An [[https://www.youtube.com/watch?v=RQK_DaaX34Q&list=PLEoMzSkcN8oPQtn7FQEF3D7sroZbXuPZ7][elisp]] package - Bytecode compiling, linting, and test running - Commands to handle common elisp development gotchas - CI with [[https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs][Github Actions]], configured for Darwin (MacOS) and Linux -- [[https://nixos.org/#examples][Nix]] environment for obtaining dependencies or - reproducibly developing CI locally +- [[https://nixos.org/#examples][Nix]] environment for obtaining dependencies or reproducibly developing CI + locally - Licensing, [[https://developercertificate.org/][DCO]], and DCO sign-off checks for PR's - [[https://github.com/melpa/melpa][MELPA]] publishing compatible @@ -52,6 +55,7 @@ answer all the questions. - Root directory you want to clone to - Package name + - Package prefix - Author name - Github user or organization - Email address @@ -174,13 +178,18 @@ answer all the questions. *** Manual Loading & Reloading + To manually unload, run built-in command ~unload-feature~ and select your + package name. If you do not unload, reloading has no effect and you will see + stale behavior. + + Next, add the package to your load-path and then require it or, more + directly, call =emacs-lisp-byte-compile-and-load= or + =emacs-lisp-native-compile-and-load=. + Especially in bootstrap situations such as working on this package itself, you cannot unload the package in the middle of a command. Some commands have a =no-reload= variant just for this circumstance. - Call ~unload-feature~ and select your package name. If you do not unload, - reloading has no effect and you will see stale behavior. - When using locally installed packages such as with straight, =straight-rebuild-pacakge= will rebuild but *not* reload. @@ -429,7 +438,7 @@ answer all the questions. can also set the signature flag this way. **** Automatic GPG signing with per-project keys - + In order to specify which projects you intend to sign with which keys, you will want to configure your git client using path-specific configurations. @@ -492,44 +501,57 @@ answer all the questions. * Package scope and relation to other work - This repository mainly captures the annoying work necessary to set up a new - repository with everyting working. By focusing on just one minimal task, - cloning itself and renaming, there is very little work a user will need to - identify and remove to reach the clean foundation. + There are two functional goals of this repository: + + - Automate the annoying work necessary to set up a new repository + - Streamline common elisp development workflows Commands within this package will focus on cleaner integration of the tests and lints with Emacs. There has been a lot of work in this area, but much of it is - tangled with dependency management and sandbox creation. + tangled with dependency management and sandbox creation. Much of the work is + done in languages other than elisp and focused on non-interactive workflows + with no interactive integration on top. -** Dependency Management + Providing close to out-of-box CI is a big focus. By making it easier to + qualify changes from other users, it becomes less burdonsome to maintain + software, and by extension, less burdensom to publish and create software. The + effect is to drive creation of elisp in a way that can accelerate the flow of + elisp into Emacs itself. - Many tools for testing Emacs packages provide dependency management and loading - those dependencies into a fresh Emacs instance. This package will never attempt - to manage dependencies. Dependencies will always be expressed through the Nix - flake expressions and at most a lock file describing a frozen set of Emacs - dependencies. +** Dependency Management - Use of the [[https://github.com/nix-community/emacs-overlay][Emacs Nix Overlay]] is a simple way of stating and obtaining elisp - dependencies for now. Non-elisp dependencies are trivially provided form - nixpkgs. Nix is extremely reliable at dependency management, and it is no - surprise that much complexity is normalized away by just the basic behavior - model of Nix. In addition, *if your project needs or includes additional binary - dependencies or modules*, Nix is an excellent way to provide them to CI and - users. + This repository uses pure dependency management and then levarages it to + provide dependencies for development and CI environments. The resulting user + experience is built around CI for reproducibility and interactive testing for + development speed. + + Because most elisp dependencies can be obtained without extensive system + dependency management, many tools for testing Emacs packages provide + dependency management and loading those dependencies into a fresh Emacs + instance. This aligns well with ad-hoc sandboxed local testing. This was + fine in the old days of impure dependency management and dirty environments. + + The [[https://github.com/nix-community/emacs-overlay][Emacs Nix Overlay]] and Emacs support within nixpkgs make it possible to + stating and obtaining elisp dependencies in a completely pure way. Non-elisp + dependencies are trivially provided form nixpkgs. Nix is extremely reliable + at dependency management, and it is no surprise that much complexity is + normalized away by just the basic behavior model of Nix. In addition, *if + your project needs or includes additional binary dependencies or modules*, + Nix is an excellent way to provide them to CI and users. ** Discovering and Running Tests & Lints - This repository uses very bare elisp that can be run with just one Emacs switch - in most cases. The Makefile merely exposes this interface with the even more - familiar make style of user interaction. + During development, the commands provided under the =erk-= prefix make it + more convenient to reload your package and test features. You can run the + ert tests for a project while working on multiple packages. - The CI scripts are arranged to present a useful environment first. The commands - to invoke tests follow. If the commands need to be changed, it is - straightforward to change them /independently of how you provide dependencies/. - Just be sure to propagate changes to the Makefile and README of your project. + During CI, this repository uses an elisp shim for discovering and running + tests. The commands within the package for convenience during development + are not depeneded upon during CI. - Future versions of this project will continue to favor elisp scripts for test - discovery and integration with Emacs. Make and bash will be minimized. + The CI actions obtain an environment with dependencies using Nix, so this can + also be done locally using Nix, meaning re-creating environments is available + to the user without leaning on CI. ** Comparisons @@ -556,23 +578,26 @@ answer all the questions. * Contributing First decide if you want to work on this repository or fork it to something - entirely different. Non-exhaustive list of changes that are very welcome: + entirely different. + + Non-exhaustive list of changes that are very welcome: - - To the maximum degree possible, this project should lean on elisp as a CLI - script backend - - Running additional kinds of tests - - Running additional lints + - More interactive integrations with high-value elisp development workflows + - Running additional or better kinds of tests & lints - Fix bugs - Expose trivial options where a structural choice has limited them unnecessarily - Behave the same, but with a less complicated code - - Guix support + - Guix or other pure dependency management support Changes will likely be rejected if it is aimed at: - - Managing dependencies outside of Nix expressions other than a package that is - supposed to manage dependencies or test obtaining dependencies in a - user-present use case + - Non-elisp interfaces meant for invocation outside of Emacs or with scripting + implemented in a language besides elisp. + - Managing dependencies outside of Nix (or other pure dependency management) + expressions + - CI infrastructure support for non-Actions infrastructure (which cannot be + tested in this repo) - Backwards compatibility for Emacs two versions behind next release. Master, current stable release, and release - 1 are the only versions being supported - pre-flake Nix support