Document and explain the internals of the build process and main just command to improve DX

[ivanminutillo]

From this elixir thread

"I think the decision to use just as the build tool and having the various components be split in different repos that are then pulled in when setting the dev environment, add to the learning curve to get onboarded. I am guessing when things work this wouldn’t be a problem. In my case it didnt work right away and when I started debugging, that’s when I realized how the project is structured in an unusual way compared to other elixir projects.

Maybe a high level overview of the build process and what all happens when one runs the just config or just setup commands could help simplify things 😃 "

[dennyabrain]

Hey! I wrote that comment. I was very interested in learning what the Justfile does and sharing some of my notes in case its useful.

I am new to Just. So I needed to understand the following :

1. Just runs project specific commands. Commands are called recipes.
2. recipe names can be prefixed with _ in which case they become private or @ in which case their name is suppressed in logs
3. Understanding just syntax. In the following recipe definition init services="db": _pre-init The recipe name is init. It is passed a parameter services with default value db. Recipe named _pre-init is run before init

I also tried to create a rough dependency graph of the setup-dev recipe.

flowchart TD
    setupDev(setup-dev) --> buildNode(build) 

    subgraph Build Docker Image. Copy Code from Extensions and current flavour to Main project
        assetsLn(
            _assets-ln: 

            Creates a symbolic link to 
            extensions/bonfire_ui_common/assets 
            in the current working directory

        )
        preInit(
            _pre-init: 

            Make data directory
            Make priv/repo directory
            Copy files from FLAVOUR_PATH/repo into ./priv/repo
            Delete ./data/current_flavour
            Make a symbolic link from ../$FLAVOUR_PATH to ./data/current_flavour
            Make priv/static/public directory
        )
        init(
            init: 
        )
        buildNode(
            build : Build the docker image

            Make deps directory
            Build docker image based on WITH_DOCKER value
        )

        services(
            services : Start background docker services eg. db and search backends.

            based on MIX_ENV, Start background docker services. 
            eg. db and search backends. 
        )

        servicesCondition{
            MIX_ENV == 'prod'
        }

        relServices(
            rel-services

            Start release related docker services
        )

        devServices(
            dev-services

            Start dev related docker services
        )

        assetsLn --> preInit --> init --> buildNode

        init --> services --> servicesCondition

        servicesCondition --YES--> relServices
        servicesCondition --NO--> devServices
    end

From reading the documentation and the justfile, what I have gathered so far is setup-dev does the following :

1. doing docker related tasks depending on the WITH_DOCKER value
2. cloning the various extensions from their repository and moving them into the main project's usual location.
3. copying flavour specific files to their right location

From the graph, I can point out some issues that I think will stump newbies.

1. Some recipes have generic names (init, pre_init)
2. Some recipes lack a comment to explain what they do.
3. The FLAVOUR and WITH_DOCKER flag cause a lot of conditional branching around in the justfile making it slightly harder to follow the sequence of recipes.

I understand that refactoring the Justfile is not a priority at this point so maybe a better approach could be to solve it in the documentation. Maybe we can write a high level description of the various things that need to happen in order for bonfire to start and which recipes are involved in doing what. I have also noticed some naming convention in the recipes that indicate a certain grouping, like prefixing the recipe names with rel-, deps-, update- etc. So if there is a logical grouping already, explaining that to newbies might help demistify this more.

[ivanminutillo]

this is great! thanks a lot! We've setup a matrix room to coordinate around documentation and Q&A, if you're interested in joining https://matrix.to/#/#bonfire-documentation:matrix.org