RFC: project initialization, module creation, and the Git Root

[safeer]

The current process to create an FTL project follows. The result is an ftl-project.toml file and a module mymodule.

git init .
ftl init go . mymodule

FTL currently makes an assumption that a project is in a Git repository, so commands such as ftl init will fail if git init is not run first. This made sense when the ftl-project.toml file wasn't required, since the root of the project was assumed to be the Git root, but when a single ftl-project.toml file is required, does this still make sense?

Up until recently, ftl init only created a module, since ftl-project.toml was not required. It now creates a ftl-project.toml file in addition to a module mymodule. Does it still make sense to overload the init command?

Proposal: separate out ftl init from a new command, something like ftl module.

ftl init .
ftl module go mymodule

Here, ftl init would create a ftl-project.toml file, and maybe create a git repository if one doesn't exist?

• Option 1: create a git repository, with .gitignore etc as we do now
• Option 2: prompt the user about creating a git repository
• Option 3: don't create a git repository, and no longer rely on there being a Git root
  • In this case, to find the project root, we'd walk up the dir tree until we find an ftl-project.toml

Does this seem cleaner?

[wesbillman]

Nice! Thanks @safeer

Maybe we should consider having ftl module be a top level command with some sub commands like new? It might be useful for future module focused commands as well perhaps.

ftl module new go . mymodule

It's a bit more verbose, but could leave room for future commands.

[alecthomas]

I agree the new requirement doesn't work well in some cases, but I think we can still keep just ftl init and simply create an ftl-project.toml file in the current working directory if one isn't found.

The rationale is that if a file is manually created we want to use it, but we also want to pick a default location when possible.

Have a look at #1784, the semantics are the following:

1. If the FTL_CONFIG environment variable is set, it is used directly.
2. Otherwise the parent directories are searched for an existing file.
3. If not found and a git root is present, ${GIT_ROOT}/ftl-project.toml is returned whether the file exists or not.
4. Finally if not found elsewhere, the current directory is used whether the file exists or not.

Basically under all circumstances, a config file path will be returned.

I think this makes sense, and will give a decent user experience WDWT?

[alecthomas]

OTOH maybe it is preferable to have separate "init" and use phases, akin to "git init ." and "git add foo".

How about this to create the ftl-project.toml:

ftl init <dir>

And just:

ftl new <language> <dir>

To create a new module in the given directory.

eg.

ftl init .
ftl new go backend/modules/echo

[alecthomas]

Actually this will be nice too, because we can expose all of the undocumented config entries like module-dirs and startup as flags to ftl init, and can set ftl-min-version.

I think this is a good idea.

[alecthomas]

I don't think it should create a git repo, but what Hermit does is that if a git repo exists, it will add the newly created files to git automatically, unless --no-git is passed.

[safeer]

Actually this will be nice too, because we can expose all of the undocumented config entries like module-dirs and startup as flags to ftl init, and can set ftl-min-version.

I'm digging it.

Basically under all circumstances, a config file path will be returned.

So in a world with a separate ftl init phase and a required ftl-project.toml, would it make sense to error out if the file isn't found instead of an implicit creation? This would funnel all project file creation through a single path which seems like it'd make reasoning easier

I don't think it should create a git repo, but what Hermit does is that if a git repo exists, it will add the newly created files to git automatically, unless --no-git is passed.

I dig this too. Supporting FTL outside of a git hierarchy would also mean making .gitignore updates conditional and removing usage of the git root entirely, I believe?

[safeer]

One thing I've noticed that the scaffolding, specifically for Hermit's bin/ directory is language specific. I was hoping to move that to the ftl init phase but that would require specifying the language i.e. ftl init go

This won't really work when supporting different languages in the same project. So adding a new module would be ftl new kotlin . mymodule --hermit to get the kotlin-specific tools into bin/

Just would be nice to keep that --hermit flag in init :)

[safeer]

I'm thinking that there should be some scaffolding during ftl init . --hermit that at leasts brings things into bin/ like: hermit, hermit.hcl, README.hermit.md, the ftl* symlinks, etc

Then when ftl new go . mymodule is run, if there is a bin/ it will pull in the Go specific tooling: go, gofmt

And ftl new kotlin . myothermodule would do the same if there's a bin/ and pull in the Kotlin tooling: jar, javac, mvn, etc.

This way the hermit flag is only specified at init and future language tooling would be additive. Thoughts?

[alecthomas]

Yeah that sounds reasonable to me. We could also add hermit = true to the ftl-project.toml file.

[alecthomas]

So in a world with a separate ftl init phase and a required ftl-project.toml, would it make sense to error out if the file isn't found instead of an implicit creation? This would funnel all project file creation through a single path which seems like it'd make reasoning easier

Definitely. I think we just search ancestor directories to find the config, and if not found we error.

I don't think it should create a git repo, but what Hermit does is that if a git repo exists, it will add the newly created files to git automatically, unless --no-git is passed.

I dig this too. Supporting FTL outside of a git hierarchy would also mean making .gitignore updates conditional and removing usage of the git root entirely, I believe?

Use of git should be conditional currently, and should remain so yeah.