Project status

(Penny speaking here; my views are only my own, etc. etc.)

This is a less formal page, where I discuss the current state of JuliaFormatter development and some long-term goals.

Stability

At present, I do not consider it possible to guarantee that formatted output will not change between versions.

That is to say, the version of JuliaFormatter guarantees its public library API, along with its configuration options. However, I cannot give a blanket guarantee that v2.p.q will not change the formatting of v2.r.s. (Note that this is consistent with the way that JuliaFormatter has been developed to date.)

The main reason for this is because JuliaFormatter v2 is still quite buggy. It fails to format a fair amount of code in the wild: for example, it can't format JuliaLang/julia@v1.12.6. Even a cursory look at the issue tracker will show that there are still many things that are broken with v2!

A secondary reason is that the codebase is in what I consider to be a local minimum. It often happens to work, but there are for example several functions which are overloaded in different places for different purposes. There is definitely some refactoring needed to make the code easier to maintain and easier to improve. It is very hard to do this without breaking some formatting somewhere.

Another lesser point is that JuliaFormatter is designed to be customisable and it's not trivial at all to predict how the introduction of a new formatting option interacts with the rest of the codebase.

If you want stability, you should pin the version of JuliaFormatter you use. In fact, I believe that even if JuliaFormatter was more stable, this is still a good idea. The reason for this is because formatting changes should be separate from other code changes, and should be only introduced as part of an intentional upgrade. This avoids noisy diffs, and also plays well with the git blame --ignore-rev option: if you have a commit that consists only of formatting changes, you can add that to .git-blame-ignore-revs, and GitHub/GitLab will ignore that commit when showing the history of a file (see e.g. this post).

Testing

The discussion above naturally leads us onto the question of, how do we know if some formatting somewhere is broken by a given change? Right now, the only true test of JuliaFormatter's output is in its unit tests. The unit tests are quite sparse, but even if they were greatly expanded, there is no real way that unit tests can even hope to cover the full range of Julia code in the wild.

To this end, I think it's important to run regression tests against large codebases. I've recently introduced a GitHub Action workflow which runs two versions of JuliaFormatter (PR base + PR head) against a named GitHub repository, and compares the diff. See, for example, this PR.

I'd like to add some of these checks into CI. However, this of course means that I have to hardcode some combinations of repositories + formatting options. Nominations for codebases are very welcome.

Long-term goals

I would very much like for JuliaFormatter v3 to start offering some stability guarantees. I'm yet unsure of the exact form of this: there has to be some balance between stability, and the ability to make improvements to the codebase.

I also would not recommend holding your breath for a v3 release. This is a project I work on in my spare time, and although I think I'm a pretty decent software engineer, this is naturally a difficult codebase because of the combinatorial nature of source code. I really do recognise that this is an important project for the Julia ecosystem, and I will indeed try my best(!), but I cannot over-promise things: note that I want to protect myself against open-source burnout as well.