Contributing to Akkoma¶
You wish to add a new feature in Akkoma, but don't know how to proceed? This guide takes you through the various steps of the development and contribution process.
Come say hi to us in the #akkoma-dev chat room!
Akkoma is the back-end. Clients have their own repositories and often separate projects. You can check what clients work with Akkoma on the clients page. If you maintain a working client not listed yet, feel free to make a PR to these docs!
For resources on APIs and such, check the sidebar of this page.
The docs are written in Markdown, including certain extensions, and can be found in the docs folder of the Akkoma repo. The content itself is stored in the
Akkoma is written in Elixir and uses Postgresql for database. We use Git for collaboration and tracking code changes. Furthermore it can typically run on Unix and Unix-like OS'es. For development, you should use an OS which can run Akkoma.
It's good to have at least some basic understanding of at least Git and Elixir. If this is completely new for you, there's some videos explaining Git and Codeberg has a nice article explaining the typical pull requests Git flow. For Elixir, you can follow Elixir's own Getting Started guide.
Setting up a development environment¶
The best way to start is getting the software to run from source so you can start poking on it. Check out the guides for setting up an Akkoma instance for development.
Akkoma has several modules. There are modules for uploading, upload filters, translators... The most famous ones are without a doubt the MRF policies. Modules are often self contained and a good way to start with development because you don't have to think about much more than just the module itself. We even have an example on writing your own MRF policy!
Another easy entry point is the mix tasks. They too are often self contained and don't need you to go through much of the code.
Activity Streams/Activity Pub¶
Akkoma uses Activity Streams for both federation, as well as internal representation. It may be interesting to at least go over the specifications of Activity Pub, Activity Streams 2.0, and Activity Streams Vocabulary. Note that these are not enough to have a full grasp of how everything works, but should at least give you the basics to understand how messages are passed between and inside Akkoma instances.
When you make changes, you're expected to create a Pull Request. You don't have to wait until you finish to create the PR, but please do prefix the title of the PR with "WIP: " for as long as you're still working on it. The sooner you create your PR, the sooner people know what you are working on and the sooner you can get feedback and, if needed, help. You can then simply keep working on it until you are finished.
When doing changes, don't forget to add it to the relevant parts of the CHANGELOG.md.
You're expected to write tests. While code is generally stored in the
lib directory, tests are stored in the
test directory using a similar folder structure. Feel free to peak at other tests to see how they are done. Obviously tests are expected to pass and properly test the functionality you added. If you feel really confident, you could even try to write a test first and then write the code needed to make it pass!
Code is formatted using the default formatter that comes with Elixir. You can format a file with e.g.
mix format /path/to/file.ex. To check if everything is properly formatted, you can run
mix format --check-formatted.