-
-
Notifications
You must be signed in to change notification settings - Fork 48
Make Unbricked into a submodule #124
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
Pulling specific versions of its files via `git2` Fixes #110 (by keeping the variable even after outliving its usefulness)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah sorry but this became too complex to be worth it. It brings added complexity, code, maintenance burden for no advantage over a simple, clean, plain folder organisations of the code revisions/versions we want of the tutorial code.
It's clear that we need to be able to comfortably access, contribute and properly diff various, incremental versions of the tutorial code. I suggest we go to a simple folder solution in which every single revision is directly accessible. If we really want to make it git diff-able etc we can script the creation of a git repo out of that, but not the other way around, please.
It brings several advantages, as outlined in the OP's "Motivation" section. |
None of the "motivation" points (please do correct me if I'm wrong) are directly enabled by having the code as a git sub repository (with all the annexed additional burden of not having direct access to any but the last "snapshot" of the code which is now behind a git commit). If you really want a "rebase" whenever you change a previous revision of the code, we can script git to do so for us (and eventually put it in CI etc), but I really do not want to ask contributors to go through all of this just to change how the code is presented in a Lesson, when we can simply have multiple "snapshots" of each necessary code version (per lesson) in a different folder and directly modify them. |
In BlocksDS I use submodules heavily, and I'm not sure it's the best solution here. Submodules make sense when some specific thing makes sense as a standalone project. The additional handholding that submodules require is pretty annoying, and it can surprise beginners. It also means people that clone this repository will have to start using
You will still have them if you split this repository into two, but the conflicts will only show up in one of the two repositories normally.
Can't you do that right now without submodules? I agree it makes sense. |
@AntonioND Thanks for the comment. Here, on top of the normal "submodule" usage, we have an additional requirement: we're preseting the code in different "states", as we walk the reader through the iterations. The proposed approach requires you to go in a specific commit of the code repository, change it, rebase/rewrite history every time you want to change the code you are presenting at a specific lesson, so it's really an additional layer of complexity and hiding things "behind" git. I.e. Lesson 1 presents "initial" state of the code -> Code commit 1 So, every time I want to change code that we present in lesson 2 I have to checkout that specific commit in the history of the code submodule, change it, go through the rebase, fix conflict, rewrite history, .. |
Oh, I hadn't seen that. I think that's very inconvenient as well. Whenever you want to update an old commit you have to go through the process you've mentioned (and fix potential conflicts!), but then you also need to change all links that may point to each commit because all the hashes will change after a rebase. The right approach here is to have different folders. There are many examples out there, but a couple come to mind right now:
I understand the appeal of having a git diff for each commit, but you can also get a diff by doing |
This is the current mode of operation, and #110 shows that it's failing. This PR is an effort to fix the issue; submodules may not be the right tool for that job, but an alternative is needed then, because the statu quo is bad. I do not have any better ideas.
I'm not sure what “them” is referring to here. And what conflicts? I was saying that making each modification a separate commit allows editing via
This is the entire point: propagating the changes to every subsequent lesson. Not doing that has led to, and I know I'm repeating myself, #110 at least. Yes, rebasing is inconvenient, but that's even more so the case without a tool's help, because you need to manually generate and audit all of the diffs. Therefore, I don't think having multiple “flat” directories is the right approach, because it's “write-only” and harder to maintain than with tooling. |
Ah, sorry, I was referring to conflicts. If you would have a PR that touches the tutorial and the code, and now you have two PRs (one for the tutorial, another one for the code), you will still have conflicts. Git was designed to have an immutable history. If your workflow involves changing the history all the time, it's a bad workflow for git. The whole point of the history of a repository is to know how things have been changing and to know when problems have been added, and who has made changes. Not to be an artificial way to store different versions of a tutorial in which you expect your readers to actually see all versions as they read the tutorial. Instead of just downloading a zip file they would have to clone the repository and use git checkout every time. Also, how do you even expect people to contribute to the model that you're thinking about? Only people with force-push permissions will be able to edit this. It would also be awkward to test. If you ever want a pipeline that builds all chapters of the tutorial, you'd have to checkout every commit and build that, which is far worse than just... having a makefile that builds all the projects inside each folder. Issue #110 isn't even a big issue, it's just an unused variable. There is no need to use a completely non-standard workflow just for that.
I will show you another example of a super famous tutorial, with the same issues as yours (lessons that build on the previous ones), and where they just use regular folders: https://github.com/gamedev-net/nehe-opengl/tree/master/linux Find one single tutorial that does things the way you're suggesting. I think the main problem is that organizing the tutorial around one single game isn't a very scalable solution. There are some things that just don't make sense in one specific game. If you want to show them, you need to shoehorn them somehow. That's why you have a variable that you only use in one intermediate chapter. Some chapters could just have their own independent example that doesn't depend on the rest of the game. This is why I've dropped Patater's tutorial for DS and I've started writing my own tutorial. Instead of trying to show someone how to write a game, I show how to use all parts of the DS with small examples: https://blocksds.skylyrac.net/tutorial/ That's not what you want to do with this tutorial, and I understand that, but there's a middle ground in which most of the tutorial can show how to develop a game and some sections can show how to build a second game, or some small demo. |
#110 is only one example, there were other "desync" problems found during the making of the tutorial itself, and I expect that future updates will likewise be incomplete. But this is doomed to be rejected, so, closing. |
What I am trying to suggest, @ISSOtm , is : couldn't we try the rebase approach without setting up the code as a git repository? E.g. scripting the creation of git repo on the spot and run the rebase between two revisions? |
If you can figure out how to reliably do that, sure. |
Pulling specific versions of its files via
git2
.Fixes #110 (by keeping the variable even after outliving its usefulness, so maybe not a real fix)
Paves the way for #117, since each lesson can now link to a commit in a repo, and possibly #17 also.
Motivation
.asm
files are now served “inline”, instead of via GitHub. (This is not strictly necessary, but I think it makes more sense.)Drawbacks
unbricked
is now a submodule, the associated submodule issues (git clone --recursive
,git archive
no longer working...) are brought in.unbricked
now requires PRing two separate repos (first the submodule, then this repo to update the commit being pointed at); and the former is not really a PR, since we need to keep one commit per lesson. OTOH it should reduce QA back-and-forth on PRs made to it.Notes
I expect that the
unbricked
repo would be moved to thegbdev
org before actually merging this.I also expect to perform the same modifications to Galactic Armada afterwards, if this is accepted.