Skip to content

Latest commit

 

History

History
102 lines (70 loc) · 4.78 KB

development-guidelines.org

File metadata and controls

102 lines (70 loc) · 4.78 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
  • Emacs 31

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.

Icons

Emacs+ comes with multiple optional icons to use instead of the default one. Due to Homebrew limitations, each icon has a separate option in the form --with-NAME-icon, where NAME must match the ^[a-zA-Z\-0-9]+$ regexp.

Almost automated flow

Follow these simple steps to add a new icon.

  1. Come with appropriate name for the icon. The name must contain only alphanumeric symbols and dashes. A good idea to combine author name and icon name.
  2. Add a 1024x1024 NAME.png file to icons/original folder.
  3. Run iconset script in the root of the repository. It will generate all previews, icon sets, and workflows.
  4. Modify Icons section of the README.org file. Don’t forget to add links to source and author.

Manual flow

Follow these simple steps to add a new icon.

  1. Come with appropriate name for the icon. The name must contain only alphanumeric symbols and dashes. A good idea to combine author name and icon name.
  2. Add a 1024x1024 NAME.png file to icons/original folder.
  3. Add a 128x128 NAME_128.png file to icons/preview folder.
  4. Add a NAME.icns file to icons folder.
  5. Add the new icon to Library/Icons.rb (name and hash).
  6. Create a workflow in the .github/workflows directory for the new icon. It might sound stupid but we had enough issues with broken icons. Just copy-paste an existing workflow and modify it for the new icon.
  7. Modify Icons section of the README.org file. Don’t forget to add links to source and author.

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