Skip to content

Latest commit

 

History

History
97 lines (73 loc) · 3.84 KB

development-guidelines.org

File metadata and controls

97 lines (73 loc) · 3.84 KB
Raw

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
  • Emacs 27
  • Emacs 28
  • Emacs 29
  • Emacs 30

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.

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).