Contributor's Notes / FAQ

If you are interested in contributing, this is the place to start.

Table of Contents

1 What can I do to help?

2023 will be the year of Fern. See the Fern Development Roadmap.

2 Where does the development take place?

On sourcehut, here:

Sourcehut is streamlined for the mailing-list workflow.

3 How do I use the mailing lists?

There are a lot of resources provided by sourcehut itself.

Before that, one note on how sourcehut operates: everything is grouped into projects and projects may share the mailing lists and ticket trackers and even repositories.

The projects are listed here:

and the mailing lists are here:

To start a discussion, send a mail to:

  • ~project-mage/<dev>@lists.sr.ht (remove the angle brackets),

and to file a bug, send a mail here:

  • ~project-mage/<tickets>@todo.sr.ht (remove the angle brackets),

(If you are unsure that filing a ticket is what you want, just use the mailing list instead.)

To subscribe, you have to send a subscription mail to the address with +subscribe appended to the name of the list (alternatively, just find the button on the page).

So, for development, there's just one mailing list and one ticket tracker, even though there are many repositories.

To contribute code, you need to send a patchset to the mailing list. There are two ways to go about this: either use the sourcehut's web UI or git's send-mail command:

While at it, you might also want to check out:

And here's another (non-sourcehut-related) guide that you might find useful:

4 Why use mailing lists?

For one, there's no need to register (even if you send patches, in which case you can stick to git send-mail).

And with some setup like mbsync + msmtp + notmuch, you don't have to use a browser. Here's a demo of notmuch:

One can automate patch extraction from a thread, see Notmuch FAQ. Of course, any other setup is viable, even if you just stick to the web browser. But in case you are interested, here are some tutorials (but I warn you that the setup might easily consume a couple of evenings of your time):

5 What are the requirements for code?

  • 80-chars per line.

    In Emacs, you can do

    (custom-set-default 'fill-column 80)

    or

    (set-fill-column 80).

  • The standard LOOP construct is not to be used anywhere. Only iterate. It's extensible and is way more pleasant to work with. In addition, the project uses a special itr alias (instead of iter).
  • There should be test coverage where sensible. Parachute is used along with a custom test macro. Look at some existing examples to get the hang of it.
  • The mage and fern repositories consist of submodules and don't carry any actual code themselves. Submodules are independent repositories. For instance, fern contains geometry as a submodule. When you commit a change in geometry, then git status on fern will indicate that one of its submodules has changed. Just ignore that, no need to commit and push those.

  • The project uses some unicode symbols, such as λ for lambda. I highly recommend installing xah-math-input.

    (use-package xah-math-input)

    With some binding like this:

    (global-set-key (kbd "M-5") 'xah-math-input-change-to-symbol)

    you can then type lamdba, do M-5 (or what have you), and the symbol will get converted to λ.

  • The project offers a custom readtable that allows lambda shortcuts: 

    (mage.utils:in-standard-readtable)

((λ (x y) (+ x y)) 5 2) ; => 7
(#2λ(+ x0 x1) 1 3)      ; => 4

  • Code sectioning: you can use ;; * Section name syntax to designate code section, where the number of stars indicates depth: 

    ;; * Some big section
  ...
;; ** A few functions in it
  ...
;; ** And a few others
  ...
;; * Another section
  ...