Extending Lorekeeper

Since its release, many and varied extensions have been written and released for Lorekeeper. These modifications to the framework's code allow for a variety of new functionality that (given the inherently opt-in nature of extensions) allows them to serve many and in fact many different potential use cases for Lorekeeper itself.

Should you want to author an extension of your own, there are certain guidelines you should follow in the interest of making the process as smooth as possible for all participants. This article covers these, as well as registering your extension on this wiki and releasing it to the public. Note that this does not cover making the modifications themselves.

Note that this article covers the creation and releasing of extensions; for installing them, see Tutorial: Installing Extensions.

Creating an Extension

Before you begin any work, it's useful to have and/or keep in mind a few things.

• You must have a local instance on which to work.
  • This is non-negotiable when making significant changes to Lorekeeper, extension-writing included. Working in a dev environment is inherently more conducive to, well, development; in this case it includes easier display of errors, ability to simply save files and see the modifications reflected on your dev environment (without having to commit+push), and so on.
• Lorekeeper, as of v2.0.0, requires PHP 7.4...
• ... and runs on Laravel 8.

Consequently, the primary prerequisite to working on Lorekeeper in any capacity is having a local test environment set up with PHP 7.4. For more information, see Tutorial: Local Host. If you are unfamiliar with working with PHP and/or Laravel (itself a PHP-based framework), it is recommended that you familiarize yourself with their basic concepts beforehand. Depending on your learning style, you may want to dive right in and look at the existing code, do research, read documentation, or some combination thereof.

Also note that you must be willing to support extensions you author (within reason), fixing bugs and/or handling pull requests as appropriate. If for whatever reason you cannot fulfill this, it is recommended that you hand off maintenance, etc. of the extension, or to be willing to do so if someone steps forward. You are not obligated to make changes to functionality/fulfill feature requests, however.

You will also need a GitHub account, with the Lorekeeper repository forked.

Identifying the Extension's Purpose and Scope

First and foremost, you need an idea as to what your extension will do. Some potential sources of inspiration are:

• Is there a feature or function that would be helpful to you/a site you run that does not currently exist either in Lorekeeper or an extension?
• Does one of the ideas in the Community Feature Request document interest you?

You might also be hired to write an extension to serve a specific purpose.

Once you have an idea of what your extension should do, you should think about how you want to implement it. It can be helpful to think about existing structures in Lorekeeper or extensions that serve similar purposes, or might work a similar way to how your extension could work. Especially if referencing an extension, it may be helpful to consult the extension's author(s) for insight, keeping in mind to be respectful of their time and energy.

However works best for you, it can be helpful to plan out things such as:

• Database modifications
• Creation and/or editing of models
• Creation and/or editing of views

before actually writing any code. While you are doing this, it's important to keep in mind that a good extension is dynamic: it can be configured to serve a variety of potential use cases within its broadly stated purpose. This has implications in what sort of table(s) and columns you make, how they are structured, what data they must be able to hold, and so on and so forth cascading down through models and views. This may introduce complications, so it's important to account for it sooner rather than later-- so that you don't wind up needing to redo work, etc.

However, not all functions are well-suited to being made dynamic, or it would be prohibitively intensive to do so. You can make modifications to a single site just the same, hard-coding values and/or making specific assumptions about the required functionality that you would not be able to make otherwise, and this may be the most practical way to solve a given problem/provide a given functionality. While such modifications have their own merits, they are ultimately unsuited to being made extensions. This does not mean that you cannot publicly distribute the code or portions thereof (circumstances depending), as it may be helpful to others working on similar functions, but it does mean that you should not advertise it as an extension in the sense of the above.

In any case, it is helpful to have a clear idea of the function(s) your extension will have and those it will not-- or rather, to have a clearly defined scope. It is helpful to keep this relatively restricted and not change it majorly over the course of development. Of course, you may discover that it would be very helpful to have some additional minor function midway through; assuming you're willing and it's reasonable to implement it, and it is consistent with the primary purpose of the extension, there's no issue with including things like this. Or you may want to add some new functionality after having developed the extension; the considerations are similar. Rather, you will want to avoid tacking on not only additional work, but also additional functions which may muddy the purpose of your extension. Different functions may serve very different purposes to different people; you may have a whole suite of functions planned, but different sites may have use for only one or two parts of that whole. Developing each discrete function as its own extension and then combining them after the fact-- into an extension pack or simply on your own site/for your own use-- allows you to get the best of both worlds, so to speak. Additionally, it divides what may potentially be a very large amount of work into multiple discrete projects, which is likely to be more manageable to work on.

When you have completed your planning and have a clear idea of the purpose, scope, and necessary modifications required, you can move on to the next step.

Making Modifications

All extensions, without exception, must be built upon a clean and unmodified copy of a branch from the Lorekeeper repo. If you have not already, you will want to identify which branch you want to use, depending on the current state of the release cycle.

• If a release branch exists, it is recommended that you build upon it.
  • This is practical both because release branches are inherently stable-- only receiving bugfixes-- and because when the release they represent becomes the current version, extensions built upon it will already be up-to-date or close to it.
• Otherwise, it is recommended to use the current release (on master).

While it is not unviable to build on develop, it's not recommended as it incentivizes users toward a fundamentally unstable branch. Using develop, especially for a live site, is only advisable if you know what you're doing-- which users only interested in a given extension's functionality may or may not be well-equipped to handle, putting extra stress on volunteer support.

Once you have identified the branch you're going to build upon, check it out/switch to it, depending. It is now time to make the branch in which you will build your extension. You will want to select a succinct, descriptive name, preferably no more than three or four words, which summarizes the purpose of your extension. You should separate the words in the branch name using dashes - or underscores _.

• It is strongly recommended that you use the extension/ prefix for extension branches for clarity.
• Do not prefix extension branches with feature/, as feature branches are intended specifically for merging into core Lorekeeper.
  • Encouraging users to pull branches with the feature/ prefix in this way creates conflicting messages, as regular users should never pull any of these branches due to the risk of unfinished and/or unreviewed code.
  • See Contributing to Lorekeeper for more information.

Once you've created your branch, make changes as appropriate.

Note that if your planned extension includes user notifications, you should familiarize yourself with the Community Notification Standard and request a notification block if necessary.