Logging our journey improving developer experience of Bonfire

Chat / Discussions
, , , , ,
1

Two weeks ago, We asked for feedback on how to encourage more developer contributions to Bonfire, an open-source framework for building federated digital spaces. We received valuable feedback from the Elixir community and are still digesting it internally.

As a first step, we’ve decided to address some of the challenges mentioned in the thread through a series of Expeditions (1-hour 1-to-1 calls with Elixir developers).
These expeditions aim to improve different aspects of the Bonfire framework and pave the way for the awaited 1.0 release by co-designing missing pieces with communities and developers.

The first expedition, named Surveying, focuses on addressing documentation, onboarding, and developer experience. We’ve published a blog post to explain it in more detail: Bonfire Expeditions - Collaborating to Release Version 1.0

Before each call, we share a document with the participant to provide relevant details about the expedition, prerequisites, and tasks they’ll address during the session.

We document all the feedback and ideas received during the session. In this thread, I will report the feedback (without naming participants for privacy reasons) and the actions we take to iteratively improve the process.

This is an ongoing effort, and we’ll use this thread to track our work on DX and documentation. Any feedback is more than welcome. If you want to join the expedition, you can DM me on this forum or write a email to team@bonfire.cafe.

We categorized the feedback in 4 different categories: Confusing, Annoying, Errors, Improvements

Confusing

  • Documentation for running Bonfire locally is unclear and scattered across multiple sections and places, making it hard to follow.
  • There is no simple way to share the signup confirmation link with users locally.
  • Need to clone bonfire_spark to add new extension routes to the main router (This info is currently missing in the docs).
  • Running dep-clone-local returns errors even if the task is successful.
  • Unclear purpose of the declare_nav_link macro.
  • Unable to determine if a locally cloned extension is active.
  • Confusion regarding deps.path & deps.flavour.path files and what to update.

Annoying

  • Long compilation time when running setup-dev.
  • Numerous warnings appear during the setup-dev, and most of their sources are unclear.
  • Missing secrets generation part in the documentation.
  • More information needed about which secrets refer to what.
  • Server needs to be stopped and restarted after adding an extension.

Errors

  • App breaks if an active PostgreSQL is running locally, as it defaults to that instead of the Docker one.
  • Duplicated ports in docker-compose.yml return an error.
  • The just secrets command only generates secrets, the user expects that the command automatically includes the secrets in the .env file
  • just mix bonfire.account.new returns an error.
  • generate_reverse_router returns an error.
  • priv directory error (:code.priv_dir at compile time and releases - #7 by sodapopcan).
  • When cloning bonfire_spark, deps.path needs to be renamed as bonfire.
  • Cache of logged-out pages prevents seeing updates.
  • deps.flavour.path was not aliased in ./config during the just setup-dev command.

Possible Improvements

  • Use exdocs as the only source of truth for developer documentation
  • Improve the Installation doc to have a more linear flow for installing Bonfire locally.
  • Make compiling disabled extensions / from all flavors optional to speed up the setup-dev command.
  • Automatically add secrets to .env when running the just secrets command.
  • Remove the info about signing up via CLI since it’s straightforward to create a new user via GUI.
  • Use Hex to get all deps instead of Git to make the setup faster.
  • Rename bonfire_spark extension to just bonfire.
  • Add more info about the extensions that are enabled locally.
  • Add more documentation for the various files in config/flavour and how they’re used.
  • Add a check for {:error, _} and use default pathways to prevent the priv directory error.
7 Likes
2

Updates

  • We’ve consolidated the exdoc documentation as our single source of truth, deprecating the previous one. Bonfire doc is now available at doc.bonfirenetworks.org using the last version of the awesome exdoc library.
  • We’ve improved the installation doc based on the feedback we’ve received in our first expedition. Eager to see if the improvements will be meaningful for the next 1-to-1 sessions :slight_smile:
  • We’ve added the build on bonfire section on the documentation. This section includes multiple tutorials that touch the main parts of the bonfire framework.
    Some of the pages are still in TODO but available ones are:

Next steps

  • This week we will have our 2# expedition and we will gather more feedback, we hope to cut the setup time by half and make it as smooth as possible, it will require multiple iterations but we’re confident we can make it.

  • We will continue writing and improving the docs, mostly focusing on the installation, troubleshooting and the build on bonfire sections.

  • We’ll keep hearing any feedbacks coming from the elixir community, we’ve created a bonfire slack room in the elixir slack community for anyone who does not want to use matrix.

Social

4 Likes
3

The 2# expeditioner decided to install Bonfire with Docker for database and search index.
We spent a good chunk of time on the different just commands. If from one side the justfile helps developers automatising annoying and error prone tasks, from the other it risks to hide too much from the dev. We need to add more documentation to the existing just commands’ page.

Confusing

  • Confusion between the just setup & just setup-dev commands
  • Needs more docs for the just secrets command, why it also download all the deps?
  • What is the bonfire_spark extension and how differs from the bonfire-app core?
  • Does just setup-dev take care of starting docker and running the database as well?
  • Not sure what’s happening under the hood when running just setup-dev
  • Need to add to the docs to have docker runinng
  • What are the differences between a bonfire app and a phoenix app?

Errors

  • deps.flavour.path was not auto generated during the setup phase.
  • There is an error in the current installation documentation, just secrets should run after just config

Improvements

  • Adding a section on the doc about the difference between a standard phoenix app and a bonfire app (highlighting the similiarities with the Nerves scaffolding)
  • Add a data visualization about just setup-dev internals
  • Add more docs for bonfire_spark and how it differs from bonfire-app
3 Likes
4

:wave: Fellow maintainer of Bonfire chiming in to mention some improvements we made based on this feedback:

  • Automatically add generated secrets to .env when running the just secrets command (after prompting for confirmation)

  • Only compile active extensions by default in dev/test, in order to speed up deps fetching and compilation (unused extensions from all flavours are still included in prod, so that they can be enabled by admin and/or users in settings)

  • Rename bonfire_spark extension to just bonfire for simplicity

Thanks to everyone who’s participated so far :slight_smile: We look forward to the next session to continue improving the developer experience!

2 Likes
5

Please see: Bonfire Networks: An open-source framework for building federated digital spaces :smiley: