Philosophy

There are a number of guidelines for setting up the projects.

1. Reduce Trivia
2. Keep it Tidy
3. One Commit to Rule Them All

Reduce Trivia

I'm really good at memorizing things, but as I get older, I find it harder to remember tiny little details like which program is needed to build a .NET projects, if I'm using npm or yarn, or which command is needed for my formatting tools.

The primary reason for using Just as a build tool is to make it easier to know there is always one command to get into the system, no matter what the language, no matter how it is arranged.

Keep it Tidy

This ties a little into trivia, but basically when you look at a project in a forge (Foregejo, GitLab, or GitHub), there is usually a large list of files right there. You have source, lint and tool configurations, and the various supporting files like licenses.

It can get overwhelming. That is why there are merits in reducing how much information at the top level. That means putting source code in a consistent directory, moving configurations somewhere else, and putting documentation.

One Commit to Rule Them All

This is a paraphrase of the Lord of the Rings poem, but really it comes down to having everything in a commit. Too many times, I've gone to a project's wiki site and saw directions or instructions for a different version. Sometimes the project read me gives some details, other times I have to read the source.

Blog entries can also be part of this. The main reason is a blog entry might have source code that doesn't work after some refactoring. Being able to deprecate or update the code as part of the commit that requires that change makes it easier to keep everything in sync.

As much as reasonable for the project should be in the main repository and in well-known directories. In my case, I put documentation in the //docs/ folder and even news posts in the //news/ folder because then everything is tied together.