template repository to fork and learn

[shinenelson]

I came across https://jskatas.org as a reference to learning JavaScript.

I was wondering if it was a good idea to have a template repository that people could just fork and start learning by fixing the tests within the repository itself ( committing the fixed code and pushing to remote could also introduce learning some git along the way too ).

this way one could show progress and validate whether the solutions are correct with a peer who knows better.

I started using the online version and then found myself not sure whether my changes were accurate ( though I was getting the tests to pass ).

So, I thought why not just clone the repository and then do the tests locally? And as I was navigating the repository is when I got this idea.

I noticed the mention of nobody has nodejs installed globally anymore. While I don't want to argue / contest that notion, I believe that it would be of use for people to be able to just fork a repository, clone it locally, start fixing tests and learn javascript along the way. If they pushed to remote, they could get those tests validated from their peers too.

So, here's my proposal :

• create a separate template repository
• move all the test files ( with the tests failing ) into the repository.
• add a relevant package.json with relevant packages and scripts ( bonus : we could add scripts per file / category ).
• add a relevant README to show how to use the repository

... watch how people use it and gain insights to make it better

what do you think?

[wolframkriesing]

I love the idea of a template repo! really cool.
eventually also put it up on the page to spread the word about it, ala "23 people forked to solve the katas" ... i like that.

cool that you are mentioning it, funny enough this request came up a couple of days ago too and i added it to the changelog :) https://github.com/wolframkriesing/jskatas.org/blob/master/CHANGELOG.md

and the

nobody has nodejs installed globally anymore

is written in a provocative way intentionally ;)
I know its not the opinion of the masses, but hey ... (I guess I should write the blog post about it, hehe)

[shinenelson]

( wow, that's a lot of reactions. I can already feel some mind-share 😉 I love doing that as well )

well, I just spend the rest of the day attempting to create that template - shinenelson/js-katas-template.

I kind of went wolverine-style on the repository though. I ripped out everything that was 'unnecessary' to run the tests. My argument is that user's don't need all the cruft. All they need is the test files and the documentation on how to run the tests. That's all there is on the repo.

PS : I still have the upstream/master branch though.

is written in a provocative way intentionally

it didn't provoke me. I partly agree with it, but I don't agree with #DockerEverywhere though. That said, I just found it odd that it was a decision-making factor for a JavaScript project, that's all.

---

Now, to more details on what I've done with the template. ( you can look around the commits on the branch, but if you prefer a prose version, here goes )

0. source
   I started with the gh-pages branch because that I found that was the source for the website ( and it had the broken tests; master had the incorrect lines commented on the source; preparation for *.spec.js` maybe? 🤔 )
1. reorganization
   1. I moved the katas directory to the root of the directory.
   2. I found that the language directory was a common directory in all of the katas/es* directories ( except katas/es1 ), so, I made language the top-level directory and put the language directories inside them.
      that means that :
      • what was katas/es*/language is now language/es*.
      • katas/es1/learn-by-rewriting is now learn-by-rewriting/es1.
   3. I used package.json as a starting point, stripped out the unnecessary packages ( babel, etc ), cleaned-up the tests to the bare minimum.
   4. I removed katas/functional/curry.js because I couldn't figure out how to run those tests right. also, I couldn't find it on https://jskatas.org either. so, it didn't warrant to be in the template either.
   5. I removed the generated metadata files ( __all__.json and __grouped__.json )
2. SyntaxError fixes
3. actually break some tests that were passing

You should actually take a look at the last 2 commits. I might have fixed one of the reports in #71 ( in promise/basics.js ). If those are valid changes, I could put up a pull request to this repository as well. :)

---

I hope I haven't ripped out too much. I guess this would introduce a maintenance nightmare every time there are updates to the katas. I did think about it for a while, but then decided that it was better this way because this is a template repository and it should have only the absolute necessities.

I'd like to hear your thoughts / opinion / feedback on this.

[wolframkriesing]

Docker is just a tool, i used nixos for a while but i am missing the PhD one needs to understand it :). I will be happy to have a docker replacement, i just want the project to self-contain the env it runs in.

Wow, you've done quite some work already.
Let me go through it step by step.

Directory structure

Actually this is a good reason to document why the directory structure is as it is.
I usually do that in ADRs, like here https://github.com/tddbin/katas/tree/master/docs/adr
I just didn't do it for the directory structure yet.
My initial idea was to have the structure so that language stuff, like es1, es2, ... has its place but also libraries. You flipped it around, I actually like that idea too. But I dont see the advantage right now, I just see it is different. Maybe you can elaborate a bit why you changed the directory structure, maybe it makes more sense and I would adapt that in this repo too.

Building it instead of using gh-pages manually

You might have seen katafication (I called it), this is the process of making the tests fail. It and the whys are described under the link.
Since the gh-pages branch gets built by npm run build why not create the template repo the same way and let travis push the result to the template repo?

What do you think?

[shinenelson]

i just want the project to self-contain the env it runs in.

I agree to that 💯 Makes it 'reproducible' too

Wow, you've done quite some work already.

I knew at least 1 person that would use it ( me! market-of-one ), so, I went ahead and did the work.

But I dont see the advantage right now, I just see it is different. Maybe you can elaborate a bit why you changed the directory structure, maybe it makes more sense and I would adapt that in this repo too.

Actually, I saw it only now. I mean, each of the language directories ( es{6,7,8,10} ) had only one sub-directory in them before the actual test bundle directories. and all of them were the same. so, I thought why not flip it around so that would reduce the extra sub-directories in each of the language directories.

To me, it makes sense now than later. I mean, if those directories grows; like the learn-by-rewriting sub-directory in es1 and more of those comes by, then I guess, it would make more sense to organize by language than category.

Since the gh-pages branch gets built by npm run build why not create the template repo the same way and let travis push the result to the template repo?

This was exactly my thought initially ( I mentioned about the 'maintenance nightmare' in my previous comment ). Then I looked at the code that actually did the katafication. Though I liked the concept and I agreed with it; I saw an additional fork of the build step. It has a lot of 'extra' files that isn't required for the template. And incorporating those changes would mean a 'fork' in the build system ( which I imagine would eventually become build-template or something along those lines ). It seems a very simple if..else condition right now, but it might get bloated at some later point ( especially, when one is building the frontend ).

But I agree, that is way better than the 'un-scalable, unsustainable and unmaintainable' junk that I have right now. I was only thinking in terms of how I as a user would want a 'template' to look like ( how I wanted it to look like ).

aside : to be honest, my initial thought process started with writing that extra condition for making the build system publish to a different template repository ( that came about even before I opened this issue ). Then, for fun, I thought about using GitHub actions to use the same build steps, sans the frontend stuff and then publish to the template repository.

I'm open to reverting to the old directory structure and using a build system to update the template. I'm just floating my opinion; you're the decision-maker :)

[wolframkriesing]

thanks a lot for all the input. and build-template sounds very reasonable.
It is "just" putting the files in another directory and pushing that to the according repo.
I need to give it a bit of thought but currently it sounds like the way I would go.

[shinenelson]

well, in that case, I need to spend another few hours creating another template repository ;) probably not creating this time, it'd be testing.

I'm going to see how much I can tweak the existing build system to work for the template repository. I might come back with a pull request tomorrow ( if I need any changes; hopefully not ).

Meanwhile, I'd like to gently nudge you ( again ) to some questions that I raised earlier :

1. can you please look at the last 2 commits on the template repository and see if those make sense? if yes, I could open a pull request for them here.
2. ( well this wasn't a question earlier, but I'm asking now ) would you be open to migrating from Travis CI to GitHub Actions?

I guess I'll have to give you more time to think about the directory structure and hopefully see an ADR on that too? I hope I was clear enough with my thought process. If not, please feel free to ask.

PS : I didn't know ADR was a thing until today. So, thank you for teaching me that. I guess that's how you get used to working offline right? ( the irony though - building for the web while being disconnected from the web ;P )

[wolframkriesing]

re 1. I just took the chance to polish the things you mentioned, thanks a lot and pushed it. Thanks for finding and suggesting fixes. I thought I might save you the PR work.

re 2. I dont know gh actions yet, can it do the same thing? if so i am fine with that. why not. what's the advantage over travis, other than being more integrated (and proprietary)?

[shinenelson]

I dont know gh actions yet, can it do the same thing? if so i am fine with that. why not. what's the advantage over travis, other than being more integrated (and proprietary)?

I believe it should be able to do everything Travis does right now ( and probably more ). I proposed it only because of the integration thing. I don't know whether it provides any real advantages over Travis. I'm not all that experienced with Actions either, but I wanted to test it here. That's why I proposed it. I'll give it a try anyway.

PS : I'm sorry I haven't yet done the changes for the template repository that I said I would. I was busy 'learning' ecmascript. I will surely get back to it though. :)