- Development
- Reproducing CI
- License
- Developer Certificate of Origin (DCO)
- Maintaining nixpkgs versions
There are TODO’s within the document. Some are notes to add support to transient. Errata in particular is where something seems possibly broken, missing, or unnecessarily weird. Transient has been updated a lot, and many Errata were fixed. Please PR if you see something that works!
Spot something that seems inconsistent, unclear, or an example where the behavior is just odd? Please file an issue. If you can fix it, please submit a PR or patch suggestion in your issue.
Want to add a new example? It is welcome. PR please.
All changes must:
- Re-generate the
transient-showcase.el - Re-generate the the
README.md - Don’t break
org-babel-execute-source-block - Don’t break compile or tangle for the package
- Don’t break the TOC (re-generated using
org-make-toc - GPG sign your commits
This repository was created with elisp-repo-kit. (A literate org template is work in progress).
TODO this should be automated with the style of solutions from Elisp Repo Kit, using save hooks.
org-babel-tangle-file
The markdown export needs to skip the Elisp sections. You can configure this by running this expression inside the README.org buffer context. (eval-expression when inside the buffer)
(let ((org-export-exclude-tags '("export_elisp")))
(call-interactively #'org-md-export-to-markdown))CI will tangle the README, load the package, and then try to run tsc-showcase. It will also byte compile lint the package.
If you cannot reproduce a failure (or success) on CI, then you may want to switch to using nix to get a reproducible toolchain so you can further develop with frozen versions from the nix flake’s flake.lock.
nix develop .github# # loads the devShells.default from flake.nix
cd .github && direnv allow # same as above with file watching
The run-shim.el file is a small ad-hoc elisp script. You can reproduce its three commands almost identically like so:
emacs --quick --script .github/run-shim.el -- tangle
emacs --quick --script .github/run-shim.el -- load
emacs --quick --script .github/run-shim.el -- lint
This package uses elisp-lint to detect issues with byte compiling, package format, code structure and others. This is run after tangling the new package.
The configuration is found inside .github/run-shim.el. The CI run is invoked inside of ci.yml using Emacs in script mode. Most of the configuration is in the run shim.
You can run the lints manually almost the same as running tests.
nix develop .github#
# nix develop .github#emacs28
# nix develop .github#emacsGit
emacs --script .github/run-shim.el -- lint
Run erk-reload-package in one of your project files. All features in the /lisp directory will be re-compiled and loaded appropriately.
Note, during reloading, unloading the current module is forced. If other packages you use depend on the project feature, results may be unpredictable. This is one reason batch style testing can be preferred.
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.
This project is GPL3 licensed and a copy is distributed in the file, COPYING.
This project requires signed commits. Please set up your Github appropriately so that the check passes.
A GPG signed commit shows that the owner of the private key submitted the changes. Wherever signatures are recorded in chains, they can demonstrate participation in changes elsewhere and awareness of what the submitter is participating in. Corroborating user’s signature across a history of works strengthens that user’s attestation provided by DCO sign-off.
Follow these instructions before you get ready to submit a pull-request.
Refer to the Github signing commits instructions to set up your git client to add GPG signatures. File issues if you run into Emacs-specific problems.
Because signing is intended to be a conscious process, please remember to read and understand the Developer Certificate of Origin before configuring your client to automatically sign-off on commits.
In magit, set the -s switch. Use C-x C-s (transient-save) to preserve this switch on future uses. (Note, this is not per-project).You can also set the signature flag this way.
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.
Configuring git for this can be done with the following directory structure:
/home/rjdeveloper/
├── .gitconfig
└── .gitconfig.d
├── sco-linux-projects.conf
├── other-projects.conf
└── gpg-signing-projects.conf
In your root config, .gitconfig, add an includeIf directive that will load the configuration you use for projects you intend to GPG sign commits for.
[includeIf "gitdir:/home/rjdeveloper/**/gpg-signing/**/.git"] path = "~/.gitconfig.d/gpg-signing-projects.conf"
In the gpg-signing-projects.conf add your GPG signing configuration from earlier. sign adds the GPG signature automatically. File an issue if you need help with multiple GPG homes or other configurations.
[user] name = "Random J Developer" email = "[email protected]" signingkey = "5FF0EBDC623B3AD4" [commit] sign = true gpgSign = true
If you don’t like these configurations and want to individually indicate you have read and intend to apply the DCO to your changes, these commands are equivalent:
git commit -s -S --message "I don't like using .gitconfig"
# To clean up a commit
git commit --amend -s -S --no-message
# Combine with rebase to sign / sign-off multiple existing commits
git rebase -iNixpkgs has a new release about every six months. You can check their branches and tags to see what’s current. To get updated dependencies from MELPA, it’s necessary to update the emacs-overlay with nix flake lock --update-input emacs-overlay. You can also specify revs and branches if you need to roll back. There is a make shortcut: make flake-update MacOS tends to get a little less test emphasis, and so nixpkgs-darwin-<version> branches exist and are required to pass more Darwin tests before merging. This is more stable if you are on MacOS. nixpkgs-unstable or master are your other less common options.