diff --git a/.github/flake.lock b/.github/flake.lock index a033b73..7e34aff 100644 --- a/.github/flake.lock +++ b/.github/flake.lock @@ -7,14 +7,15 @@ ], "nixpkgs": [ "nixpkgs" - ] + ], + "nixpkgs-stable": "nixpkgs-stable" }, "locked": { - "lastModified": 1670637348, - "narHash": "sha256-4FLOEi02WS+St6i1MSUxGfA32FL1SFIpwWCDsABAZkk=", + "lastModified": 1697857699, + "narHash": "sha256-VGtcRMKi3w1hsPKduOqiSLVnSX1nO/2oixHV7mlVLFw=", "owner": "nix-community", "repo": "emacs-overlay", - "rev": "3a0b5dd7756173e63c2bbbe70dd5484a7463257d", + "rev": "e58f332cc035aaaf82c9c9f8e07b3e21ac977d77", "type": "github" }, "original": { @@ -40,11 +41,11 @@ }, "nixpkgs": { "locked": { - "lastModified": 1670482022, - "narHash": "sha256-xzzjWulnNMCSTEGosGaAg7sLsAtF7stA3sQljZ410/w=", + "lastModified": 1688392541, + "narHash": "sha256-lHrKvEkCPTUO+7tPfjIcb7Trk6k31rz18vkyqmkeJfY=", "owner": "nixos", "repo": "nixpkgs", - "rev": "c50e5b63e9d65ff0e70cc06b7042a72c6a6583bc", + "rev": "ea4c80b39be4c09702b0cb3b42eab59e2ba4f24b", "type": "github" }, "original": { @@ -54,6 +55,22 @@ "type": "github" } }, + "nixpkgs-stable": { + "locked": { + "lastModified": 1697655685, + "narHash": "sha256-79Kuv+QdgsVc+rkibuAgWHnh8IXrLBTOKg5nM0Qvux0=", + "owner": "NixOS", + "repo": "nixpkgs", + "rev": "80c1aab725151632ddc2a20caeb914e76dd0673c", + "type": "github" + }, + "original": { + "owner": "NixOS", + "ref": "nixos-23.05", + "repo": "nixpkgs", + "type": "github" + } + }, "root": { "inputs": { "emacs-overlay": "emacs-overlay", diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 60edaf0..146f286 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,28 +5,28 @@ Development process & infrastructure guide. # Table of Contents -- [Submitting Pull Requests](#org606a9eb) -- [Development](#orgcb8ea7d) - - [Running tests](#org2c0c140) - - [Lint and byte-compile code](#org4934777) - - [Loading and re-loading your package](#orgea5ce35) - - [Re-generating Documentation](#org3edbedc) -- [License](#org82dcc82) -- [Developer Certificate of Origin (DCO)](#orge4b9e7a) - - [Sign-off](#org06a4c0a) - - [GPG signature](#orgd1a4d6c) - - [User setup for submitting changes](#orgd2c4615) - - [Maintaining versions](#org51f9f2c) - - - +- [Submitting Pull Requests](#org1326ae4) +- [Development](#org31f34c1) + - [Running tests](#org2bb1086) + - [Lint and byte-compile code](#org5cf3e41) + - [Loading and re-loading your package](#orgbaa225f) + - [Re-generating Documentation](#org5c6b679) +- [License](#org24380ea) +- [Developer Certificate of Origin (DCO)](#org8ba3458) + - [Sign-off](#org850864d) + - [GPG signature](#org84b1181) + - [User setup for submitting changes](#orgd2f3992) + - [Maintaining versions](#orga8a041a) + + + # Submitting Pull Requests Be sure to abide by instructions in [the pull request template](../.github/pull_request_template.md). - + # Development @@ -34,7 +34,7 @@ This repository was created with [elisp-repo-kit](https://github.com/positron-so development workflows. - + ## Running tests @@ -62,7 +62,7 @@ have. **You do not need Nix to run tests pretty close to what CI does.** CI will use Nix to obtain Emacs & dependencies. - + ## Lint and byte-compile code @@ -86,7 +86,7 @@ You can run the lints manually almost the same as running tests. emacs --script .github/run-shim.el -- lint-tests - + ## Loading and re-loading your package @@ -109,7 +109,7 @@ directly, call `emacs-lisp-byte-compile-and-load` or `emacs-lisp-native-compile-and-load`. - + ## Re-generating Documentation @@ -131,7 +131,7 @@ manually type the path to the `manual.info`. Honestly, just use because they use `#+include:` directives. - + # License @@ -139,7 +139,7 @@ This package is distributed under the terms of the [included license](./COPYING) configuration, documentation, and scripts are MIT licensed. - + # Developer Certificate of Origin (DCO) @@ -152,7 +152,7 @@ A [copy of the DCO](./DCO) is distributed with this project. Read its text to understand the significance of configuring for sign-off. - + ## Sign-off @@ -163,7 +163,7 @@ following: Signed-off-by: Random J Developer - + ## GPG signature @@ -174,7 +174,7 @@ participating in. Corroborating user's signature accross a history of works strengthens that user's attestation provided by DCO sign-off. - + ## User setup for submitting changes @@ -249,7 +249,7 @@ equivalent: git rebase -i - + ## Maintaining versions diff --git a/README.md b/README.md index d700c3e..d60dc1e 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ answer all the questions. # Install ERK - (use-package erk) ; vanilla + (use-package erk) ; vanilla, assuming you have MELPA configured ;; using elpaca's with explicit recipe (use-package erk @@ -37,7 +37,7 @@ answer all the questions. (use-package erk :straight (erk :type git :host github :repo "positron-solutions/elisp-repo-kit")) - ;; or use melpa, manual load-path & require, you brave yak shaver + ;; or use manual load-path & require, you brave yak shaver ## Manual cloning @@ -63,27 +63,27 @@ your secrets for Cachix. Read the CI customization section. # Table of Contents -- [Creating Packages](#org48b1592) -- [Using ERK for development](#orgac0ff0a) - - [Find Files](#org5874675) -- [File contents and structure](#org0c0d60c) -- [Finish setting up your new GitHub repo](#orge318b14) - - [Optional Steps](#org47a615b):item: -- [Customizing CI](#orgec503c8) -- [Licensing, Developer Certificate of Origin](#orga3c035b) -- [Publishing to MELPA](#org233e8d2) - - [Creating the recipe](#org5094545) - - [Testing package build](#org2988a8d) - - [Testing stable package build](#orgdea3e92) - - [MELPA Lints](#orga70f644) -- [Maintaining versions](#org31ebd2c) -- [Package scope and relation to other work](#org7967777) - - [Dependency Management](#org9325996) - - [Discovering and Running Tests & Lints](#org4a9d138) - - [Comparisons](#org96cc0c2) -- [Contributing](#org59d67fb) -- [Footnote on FSF and Emacs Core Licensing](#org01e3d0e) -- [Shout-outs](#orgead8c3f) +- [Creating Packages](#org76092dc) +- [Using ERK for development](#orgeab3f87) + - [Find Files](#org113c37b) +- [File contents and structure](#org52cb5b5) +- [Finish setting up your new GitHub repo](#org0841de1) + - [Optional Steps](#org5c2c4a5) +- [Customizing CI](#orge90e6b2) +- [Licensing, Developer Certificate of Origin](#orga4735a0) +- [Publishing to MELPA](#org777effa) + - [Creating the recipe](#orgfa257da) + - [Testing package build](#org1562acd) + - [Testing stable package build](#org83741c7) + - [MELPA Lints](#orgd95580d) +- [Maintaining versions](#org7185a2e) +- [Package scope and relation to other work](#org296cf92) + - [Dependency Management](#orga889c00) + - [Discovering and Running Tests & Lints](#org2b447a7) + - [Comparisons](#org8ffac82) +- [Contributing](#orgd2bd13c) +- [Footnote on FSF and Emacs Core Licensing](#org2574276) +- [Shout-outs](#orgc3c8572) # Creating Packages @@ -100,7 +100,7 @@ ask you for: `erk-new` also calls `erk-rename-relicense` to rename all of the files, string replace names, and re-license to GPL3. It also changes the author and resets -the git history. Now just follow the steps in [finish setting up](#orge318b14) Have fun! +the git history. Now just follow the steps in [finish setting up](#org0841de1) Have fun! # Using ERK for development @@ -203,10 +203,10 @@ directories. You can copy this checklist to your org agenda files: -- [X] Create a repository (from [install](#org10fb556) instructions) -- [ ] Create an empty GitHub repository and check the git remote configuration +- [X] Create a repository (from [install](#org5847734) instructions) +- [ ] Create an empty GitHub repository configure it as your git remote - [ ] Set up your git commit signing (and verification so that it's obvious) - **and** [sign-off](#orga3c035b) so that it will be hypothetically [straightforward](README.md) for for FSF + **and** [sign-off](#orga4735a0) so that it will be hypothetically [straightforward](README.md) for for FSF to pull in your changes if they later change to DCO instead of copyright assignment. - [ ] Sign up for [cachix](https://app.cachix.org/) and, create a binary cache with API tokens and public @@ -219,7 +219,7 @@ You can copy this checklist to your org agenda files: `CACHIX_AUTH_TOKEN` and `CACHIX_CACHE_NAME` (settings -> secrets -> new repository secret) -\#+cindex github enabling actions +\#+cindex github allowed actions - [ ] Enable actions and add the following actions to your allowed actions list: @@ -232,19 +232,20 @@ You can copy this checklist to your org agenda files: **Note**, Python is used to run a DCO check script, nothing more. - [ ] Get your package working, pushed, actions run, and CI badges all green -- [ ] [Publish](#org233e8d2) to MELPA +- [ ] [Publish](#org777effa) to MELPA - [ ] Make a post on [reddit](https://reddit.com/r/emacs/) and [mastodon](https://emacs.ch/) about your new package -## Optional Steps :item: +## Optional Steps - [ ] Branch protect and enable check requirements for your default branch (usually master). Merge commits, verified only, and no force push are recommended settings. - [ ] Enable requiring contributors to sign-off on web-based commits -- [ ] For **security** of your Cachix secrets and any other secrets you may someday - add, require Actions approval for all outside contributors and leave - repository permissions at read-only + +- [ ] For **security** of your Cachix secrets (and any others), require + Actions approval for all outside contributors. Disabling write and + disabling creation & approval of PR's is least privilege. Cachix is somewhat optional. It's free for open-source projects. It's about as easy to sign up and generate the token as to remove the step from @@ -264,6 +265,7 @@ command arguments, so you can parameterize the invocations that way. - If you need extra elisp dependencies during CI, add them to the `epkgs` list in the flake.nix. + - If you need extra 3rd party dependencies, add them to `packages` in the call to `mkShell`. - To invoke different elisp operations, add / modify the commands in diff --git a/docs/manual.texi b/docs/manual.texi index b40b1af..6b05978 100644 --- a/docs/manual.texi +++ b/docs/manual.texi @@ -90,7 +90,7 @@ Navigating the project * Using ERK for development:: * Documenting Your Package:: * Distributing Your Package:: -* Nix:: +* Maintaining Your Package:: * Indices: Indices (1). @detailmenu @@ -159,6 +159,11 @@ Publishing to MELPA * Testing stable package build:: * MELPA Lints:: +Maintaining Your Package + +* Upgrading ERK:: +* Nix:: + Nix * Maintaining versions:: @@ -283,6 +288,12 @@ Github actions are included for CI@. @item Dependencies for CI are obtained via Nix. @item +Actions call into Elisp by running Emacs with arguments passed to +@uref{../.github/ruh-shim.el, .github/run-shim.el}. +@item +Many people install packages directly from repositories (because we like +supply-chain attacks), so keep your installation instructions up to date. +@item You are free to submit your package for distribution on MELPA etc. This package is made available on MELPA partly to maintain the structure and workflows for doing so. @@ -293,7 +304,7 @@ workflows for doing so. @lisp -(use-package erk) ; vanilla +(use-package erk) ; vanilla, assuming you have MELPA configured ;; using elpaca's with explicit recipe (use-package erk @@ -303,7 +314,7 @@ workflows for doing so. (use-package erk :straight (erk :type git :host github :repo "positron-solutions/elisp-repo-kit")) -;; or use melpa, manual load-path & require, you brave yak shaver +;; or use manual load-path & require, you brave yak shaver @end lisp @@ -800,7 +811,7 @@ You can copy this checklist to your org agenda files: @item Create a repository (from @ref{Install ERK, , install} instructions) @item -Create an empty GitHub repository and check the git remote configuration +Create an empty GitHub repository configure it as your git remote @item Set up your git commit signing (and verification so that it's obvious) @strong{and} @ref{Licensing Developer Certificate of Origin, , sign-off} so that it will be hypothetically @uref{README.org, straightforward} for for FSF @@ -818,7 +829,7 @@ Add repository secrets necessary for your GitHub actions @code{CACHIX_AUTH_TOKEN} and @code{CACHIX_CACHE_NAME} (settings -> secrets -> new repository secret) @end itemize -#+cindex github enabling actions +#+cindex github allowed actions @itemize @item Enable actions and add the following actions to your allowed actions list: @@ -847,9 +858,9 @@ Make a post on @uref{https://reddit.com/r/emacs/, reddit} and @uref{https://emac @end menu @node Optional Steps -@subsection Optional Steps :item: +@subsection Optional Steps -@cindex security github actions +@cindex security github branch protect @itemize @item Branch protect and enable check requirements for your default branch @@ -857,10 +868,13 @@ Branch protect and enable check requirements for your default branch recommended settings. @item Enable requiring contributors to sign-off on web-based commits +@end itemize +@cindex security github actions +@itemize @item -For @strong{security} of your Cachix secrets and any other secrets you may someday -add, require Actions approval for all outside contributors and leave -repository permissions at read-only +For @strong{security} of your Cachix secrets (and any others), require +Actions approval for all outside contributors. Disabling write and +disabling creation & approval of PR's is least privilege. @end itemize Cachix is somewhat optional. It's free for open-source projects. It's @@ -883,6 +897,9 @@ command arguments, so you can parameterize the invocations that way. @item If you need extra elisp dependencies during CI, add them to the @code{epkgs} list in the flake.nix. +@end itemize +@cindex nix adding 3rd party dependencies +@itemize @item If you need extra 3rd party dependencies, add them to @code{packages} in the call to @code{mkShell}. @@ -1017,8 +1034,77 @@ If everything works, you are ready to make a pull request to MELPA@. Push your changes and check all the boxes in the PR template except the one that requires you to read the instructions. +@node Maintaining Your Package +@chapter Maintaining Your Package + +Keeping your project fresh. + +@menu +* Upgrading ERK:: +* Nix:: +@end menu + +@node Upgrading ERK +@section Upgrading ERK + +After creating an ERK project, it becomes independent with respect to version +control and is not expected to maintain commit compatibility (this is a +terrible idea, so don't try it). + +Many files don't actually change much from project to project. Here's a list +of files that you generally can just copy and enjoy the updates for: + +@itemize +@item +.github/pull_request_template.md +@item +docs/CONTRIBUTING.org +@end itemize + +Some files are usually tweaked, but only a little bit. Drastic overhauls +will be mentioned in change notes. You probably want to update by hand: + +@itemize +@item +.github/run-shim.el +@item +.github/workflows/dco.yml +@item +.github/workflows/ci.yml +@item +.github/flake.nix +@end itemize + +Upgrades to ERK will mention if any values need to be changed before copying +any project-indpendent files. @strong{Changes to github actions will require you to +update the approved actions setting.} + +Other files which occasionally receive updates, but changes that you likely +@strong{do not} want at all: + +@itemize +@item +docs/README.org +@item +docs/manual.org +@end itemize + +These files are @strong{generated}, so you can ignore upstream changes even though +they are under version control: + +@itemize +@item +.github/flake.lock +@item +README.md +@item +CONTRIBUTING.md +@item +docs/manual.texi +@end itemize + @node Nix -@chapter Nix +@section Nix By using Nix, your repository can declare a fixed set of dependencies for development and testing. Not just Elisp dependencies, but also 3rd party @@ -1031,7 +1117,7 @@ dependencies. @end menu @node Maintaining versions -@section Maintaining versions +@subsection Maintaining versions @cindex nix dependency updating @@ -1054,7 +1140,7 @@ nix flake lock --update-input emacs-overlay @end example @node Customizing Versions -@section Customizing Versions +@subsection Customizing Versions @cindex nix custom Emacs versions There are a lot of ways to declare specific versions of Emacs in Nix. You @@ -1123,7 +1209,7 @@ nixpkgs version, you override the specific packages by writing an overlay. If you need help, file an issue and @uref{https://github.com/sponsors/positron-solutions, consider donating to maintenance}. @node Reproducing Issues -@section Reproducing Issues +@subsection Reproducing Issues @cindex nix handling version mismaches