Skip to content

Latest commit

 

History

History
144 lines (114 loc) · 5.07 KB

development-guidelines.org

File metadata and controls

144 lines (114 loc) · 5.07 KB

Development guidelines

Over the time emacs-plus grow with different utilities for adding new features and maintaining the formula. The goal of this document is to describe important bits of this process.

Table of Contents

Pull requests

Any change to the formula should go through pull requests. Exception for this guideline is resource hash fix (e.g. when patch is changed and for some reason hash is invalid).

Pull requests give visibility to the users watching this repository. And thanks to → CI pull requests changes are built in different configurations. So it’s harder to break the formula.

CI

We’ve been using GitHub workflows to run builds. Main targets are:

  • Emacs 26 (current release version)
  • Emacs 27 (next release version)
  • Emacs 28 (development version)

Where it’s applicable, we also run builds with different → options. The lesser options are available, the easier it is to cover all scenarios. Right now coverage is not the goal.

Options

Rule of thumb here is simple. If the new feature (e.g. patch) is not experimental nor controversial, it’s better to add it unconditionally. In ideal world, all features should be controllable via Emacs Lisp, not via compilation flag and the only options should be version and icon choice.

Patches

Every patch must be added to this repository. No exceptions. Rationale is simple - external location is not controlled by emacs-plus maintainers, but if something happens to the patch outside this repository, emacs-plus suffers.

In order to help with → Pull requests and → CI, emacs-plus has some utilities that load resources and patches from the local copy of repository, even on CI. So instead of using static link to the patch

patch do
   url "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/system-appearance.patch"
   sha256 "2a0ce452b164eee3689ee0c58e1f47db368cb21b724cda56c33f6fe57d95e9b7"
 end

One should use local_patch utility function provided by EmacsBase:

local_patch "system-appearance", sha: "2a0ce452b164eee3689ee0c58e1f47db368cb21b724cda56c33f6fe57d95e9b7"

So even if you are preparing PR, add the patch to this repository.

HEAD and patches

One of the most popular issues for emacs-plus breakage on --HEAD is incompatibility of custom patches and the latest state of the code. E.g. when one of the patches can’t be applied cleanly.

In order to ease the maintenance, all of the patches for --HEAD are added to → emacs-plus-basis repository. In the nutshell, it’s just a mirror of emacs repository with patches applied on top. Every few hours, CI fetches the latest updates from emacs upstream and reapplies the patches (rebase). If it fails, there is a ready playground for fixing the patch.

And once there is a need to move updated patches to emacs-plus repository, extract_patches script from → emacs-plus-basis comes handy.

$ ./extract_patches path/to/homebrew-emacs-plus

It searches for commits with [patch] suffix in the title and extracts them as patch. It moves them to homebrew-emacs-plus directory and updates hash of patches in the formula.

Building locally

Sometimes there is a need to test the build locally without uninstalling emacs-plus (otherwise it’s impossible to make any further fixes or improvements if the build breaks). For this reason, emacs-plus repository has a build script, which installs emacs-plus-local with passed options.

$ ./build VERSION [options]
$ ./build 26
$ ./build 27
$ ./build 27 --with-no-titlebar
$ ./build 28
$ ./build 28 --with-no-titlebar

This script is super simple. It makes a copy of emacs-plus named emacs-plus-local and installs it. That way you can play with formula without uninstalling emacs-plus.

Questions?

Having questions is good. Asking them is even better. Feel free to open an issue or contact me via email (you can find it in my profile on GitHub or check the committer email).