With this pull request, I intend cs-education/sysbuild to be a single repository to hold the (sub)projects which make up the system programming playground, kind of like a monorepo.
Motivation
There are several advantages to this:
Since everything is in one place, the state of one repository is the state of the whole project
Adding new subprojects is easier, thus reducing friction to contribution. When a single feature requires contributing to two repositories (for example man page stuff in sysassets), I think it it takes more time and things are harder to keep track of
Related to the above, changes related to a single feature can be in a single pull request, as opposed to multiple pull requests to multiple repositories, making things easier to track
Single testing infrastructure, with Travis CI making sure the project works as intended (once we have integration tests, of course)
One place for documentation, discussion, issue tracking, etc.
Possible code sharing, in case we have more related projects in the future (such as a backend server)
While there may be disadvantages to this approach, we do not suffer from the major common problems of monorepos: big repository sizes, and large build times. Our repository is relatively small, and is very far from reaching the limits of git.
Functionality
To do this, the following major changes were made:
Move the web application code and related files into the webapp subdirectory
Add jor1k as a subtree of this project: currently, cs-education/jor1k is almost always being used as our own stable copy of jor1k (with the sysbuild-stable branch). Instead of maintaining a separate repository and keeping it in sync with this one, I think it is better to just keep it in this repository, and point it to the upstream s-macke/jor1k. Whenever we are ready to update our copy, we can simply use git subtree to pull in the changes and save them here. I'm not sure how upstream contributions will work, but for now, I recommend that we contribute to jor1k as a completely separate repository (with personal forks), just like we have been doing, and pull those changes in sysbuild. @angrave originally had jor1k as a submodule of this project, which I think was a good decision. The only difference is that now jor1k is a subtree instead of a submodule, because I think git subtree is easier to work with than git submodule.
Add a docs folder: now that everything is in one repository, we can also have a single place to hold any documentation, including technical descriptions, design decisions, etc.
Please read the individual commit message for more details. Moving of code from sysassets will be done in a later pull request, depending on the feedback on this one. If things go as I planned, sys, sys-staging, and sysassets will only be used for hosting and deployment. Development of code to generate those assets will be done in this repository.
With this pull request, I intend
cs-education/sysbuildto be a single repository to hold the (sub)projects which make up the system programming playground, kind of like a monorepo.Motivation
There are several advantages to this:
sysassets), I think it it takes more time and things are harder to keep track ofWhile there may be disadvantages to this approach, we do not suffer from the major common problems of monorepos: big repository sizes, and large build times. Our repository is relatively small, and is very far from reaching the limits of git.
Functionality
To do this, the following major changes were made:
webappsubdirectorycs-education/jor1kis almost always being used as our own stable copy of jor1k (with thesysbuild-stablebranch). Instead of maintaining a separate repository and keeping it in sync with this one, I think it is better to just keep it in this repository, and point it to the upstreams-macke/jor1k. Whenever we are ready to update our copy, we can simply use git subtree to pull in the changes and save them here. I'm not sure how upstream contributions will work, but for now, I recommend that we contribute to jor1k as a completely separate repository (with personal forks), just like we have been doing, and pull those changes insysbuild. @angrave originally had jor1k as a submodule of this project, which I think was a good decision. The only difference is that now jor1k is a subtree instead of a submodule, because I think git subtree is easier to work with than git submodule.Please read the individual commit message for more details. Moving of code from
sysassetswill be done in a later pull request, depending on the feedback on this one. If things go as I planned,sys,sys-staging, andsysassetswill only be used for hosting and deployment. Development of code to generate those assets will be done in this repository.