rooklift/nibbler

Resource & support file reorganisation in repository

cyqsimon opened this issue · 4 comments

cyqsimon commented

I was working on writing a better install.sh script for Linux, but it's made very difficult by how disorganised the files in this repo are (sorry, no offence). So I would like to first change that.

When it comes to file organisation, there's no rule set in stone. It's a subjective topic so naturally lots of the things I say here are going to be pretty opinionated, so feel free to disagree with any or all of this post.

TL;DR

Throwing everything into /src is pretty bad practice. I would like to put some effort in reorganising and classifying the files.

Currently everything (basically) resides in /src. However that's not the conventional purpose of the /src directory. In a more conventional compiled language, it should only contain files that are read during compilation and contribute directly towards building the executable binary.

Extending this concept to a conventionally-interpreted language like JS, /src should only contain files that are included by the bundler/packager and shipped to the end user. Following this interpretation, there are several categories of things that don't belong in there:

  • "Meta files", such as .editorconfig and .gitignore, should be under the project root
  • "Helper scripts", such as builder.py and install.sh, should be either under the project root, or in their own directory under project root (e.g. /scripts) if there are too many.
  • "External resource files" that the bundler/packager doesn't care about, such as res/*, should be in their own directory under project root (e.g. /res).

Besides the general "better organisation", I think there are very practical benefits to doing this too:

  • Packaging scripts can be significantly simplified as a result, which not only impacts this repo (builder.py), but also downstream packagers (e.g. nibbler-git on AUR).
  • Futureproofing: basically if more "non-source" files are added in the future (which is bound to happen), the repo would have to become better organised sooner or later. So the best time to do it is now.

There are several concerns but nothing unsolvable:

  • I noticed there are a few scripts in .gitignore that I assume @rooklift uses. Obviously I cannot do anything about them, so the user(s) of these scripts would have to update them by themselves.
  • Moving some files may cause some downstream breakages (3rd party packagers & forks). But since the "source files" in /src are going to be untouched, breakages are unlikely. I've also reviewed some of the public downstream code I know of, and I don't think there are any problems.

Anyways, these are my two cents regarding how things can be improved. If @rooklift as the project owner approves of these ideas, I'm happy to put in the work to move the files and update the scripts.

rooklift commented

I wanted to keep the root as empty as possible because https://github.com/rooklift/nibbler is the de facto homepage.

rooklift commented

Still I'm gonna make a branch and move things about.

cyqsimon commented

I wanted to keep the root as empty as possible because https://github.com/rooklift/nibbler is the de facto homepage.

You might want to take a look at GitHub Pages. It takes very little work to set up, and it just takes your existing README.md and renders it at https://rooklift.github.io/nibbler. If you want a clean homepage I guess this is the best option.