Maintainers: any volunteers to help advise a new track maintainer?

[kytrinyx]

@bdw429s has been doing some great work to figure out how to get the ColdFusion track off the ground, and I need a couple of volunteers who would be willing to work through the thorny part of getting a new track running: figuring out exactly what an exercise needs so that people can run the tests.

There are some great discussions in exercism/cfml#1 and an open pull request reworking the first exercise: exercism/cfml#26

You wouldn't be a co-maintainer on the track (unless you want to, of course). I'm just thinking we need a couple of advisors to help navigate all the context that is involved in an Exercism track (it's more than you think).

Thank you ❤️

[bdw429s]

Awesome, looking forward to some help :)

[bdw429s]

I see that @kytrinyx will be away for a few days. I already have a slew of questions about what's needed to get the Travis build happy for my first exercise. You can view and respond to these questions here
exercism/cfml#26

Thanks in advance!

[ilya-khadykin]

@bdw429s, I left a comment in your PR - exercism/cfml#26 (comment)

Unfortunately I am not familiar with ColdFusion and can't help with that, but feel free to ask other questions

[bdw429s]

Thank you for the comments @m-a-ge ! Maybe this a good time for you to pick up some CFML, it's a great JVM scripting language. I hear there's even a new tracking coming for it on Exercism 😉

[bdw429s]

Also, some good news. I've reached out on the Tweety pages to some of my CF mates and There's a handful of people already willing to help create some CFML examples once we can nail down how it should all work!

https://twitter.com/bdw429s/status/906365456231096320

[tleen]

@bdw429s You are doing great things bringing this track to life and it is appreciated. I know of a ColdFusion shop in my hometown and am reaching out to see if anyone there would like to participate.

[bdw429s]

Thanks @tleen ! I've been doing CFML dev for 15 years now and it's a real passion of mine to help spread the word that CF isn't the same snot nosed kid it was back in 1998 when it was templating web pages. The language has really matured along with the tools and open source engines but there's still a huge knowledge gap in the general development community. Hopefully getting love from cool sites like Exercism will help change that 😄

[bdw429s]

Thanks to the help of @m-a-ge @tleen and @Insti I've made some nice progress on my open pull for the ColdFusion track. I now have two working exercises with tests, solutions, and a Travis build in place to verifies the solutions. I have questions about what comes next in regards to documentation and when/how my pull should get merged. If anyone else is able to give me a hand, you can see my last comments here:
exercism/cfml#26 (comment)

[ilya-khadykin]

@bdw429s, left a comment exercism/cfml#1 (comment), I hope it'll help you

[bdw429s]

So here's a couple quick questions.

• Should I include a stub for the student in each exercise, like a basic class with an empty function for them to implement, or should I provide nothing at all and let the creation of the class be part of the exercise? I've seen this done a couple different ways while perusing the other tracks. I'm on the fence over which option is actually more helpful to a newcomer to the language.
• Where is the best place to store a template exercise? I'll probably create a quick CLI task runner that a contributor can run to quickly scaffold out a new exercise. Is there a convention for where to store that, or should I just stick it somewhere in the repo that makes sense (like my /tasks folder that I've created)

[petertseng]

stubs

When you have made your decision if you can record it in #114 I would appreciate it.

template exercise

I don't think there is a standard location. If it helps you, another track has placed it at https://github.com/exercism/java/tree/master/_template . It can go anywhere where the tools you write are aware of it.

[bdw429s]

Here is my first stab at all the docs. Feedback is welcome:

exercism/cfml#27

[bdw429s]

I have created another pull which introduces an exercise template to make it very easy for other contributors to create exercises: exercism/cfml#28
This comes with a CLI task runner (written in CFML, of course!) that will allow future contributors to stub out all the files they need with the correct names and text replacements via a single command.

box task run tasks/ScaffoldExercise

Feedback welcome.

[bdw429s]

OK, so while I wait for those pulls to be merged (or to get the permissions to merge myself) here's my next questions.

• Where can I find all the details on exactly what files in what places I need to be modifying to create the guides for each exercise? I've seen a lot of examples and information spread around, but I'm still not 100% clear on how it all works. Some tracks have a README.md in each exercise folder, but other tracks specifically say not to do that. There's some md files some tracks have in the .meta folder and I also have seen the /docs/EXERCISE_README_INSERT.md file which I assume is at play somehow too. There's also /docs/TESTS.md but I'm not sure if that gets included at the exercise level either. Right now I haven't created any guides at all for the hello world exercise, but that's mostly because I'm not sure where to put them.
• Am I correct in assuming that I should be generating a new UUID for each exercise in ColdFusion?

[jpreese]

From my experience maintaining the C# repository, we put the README.md within the directory of the exercise.

It works well for viewing the directory on GitHub, and comes along for the ride when doing exercism fetch from the exercism CLI.

Every repo may have subtle differences due to maintainer preference or potentially language restrictions. I would just go with what makes sense to you.

[tleen]

@bdw429s I believe the current "best" way to do the exercise README's is via the configlet tool. These are the docs for how the files all relate. The configlet generate command will let you

• locally template the exercide README's for your track
• include common instructions in those READMEs
• pull problem description information from the problem-specifications repo into a problems exercise README
• add information concerning the problem's specific implementation in the track

And should anything change in the template, or the problem-specifications repo or wherever you can regenerate all the READMEs with configlet instead of doing it by hand.

These capabilities in configlet are are quite new so this may be why you don't see many exercises using .meta/ files much just yet. Plus there is always a lot of leeway to do it any other way a track feels it should be done.

Also yes to the new UUID's too. The configlet readme is a little behind, but ever since v3.1.0 it has had a configlet uuid command to generate UUIDs you can use.

configlet is becoming a one-stop-shop for a lot of track meta information work. If you have not been using it yet grab it and give it a try.

[rpottsoh]

The latest version of configlet is always available here https://github.com/exercism/configlet/releases/latest

[bdw429s]

@jpreese @tleen and @rpottsoh Thanks for the input guys. I tripped across the docs on generating the readme with the configlet the other day, but I don't think I understood enough for it to properly sink in. I read it again and it's making more sense. To confirm, it's something I run that generates the /exercises/<slug>/README.md file dynamically and then I commit that change to the repo, right?

I'm considering making a CFML CLI task runner to do this for the ColdFusion track just to customize it and for the fun of it since CF roxors 😄

[rpottsoh]

Correct. Configlet will generate the readmes, you'll then need to commit the changes, open a PR etc.

Also the linting command should be run, this will point out any configuration issues.

[bdw429s]

@rpottsoh I've been playing around with the configlet generate command tonight and for the most part it works, but I can't get it to pick up the exercises/<slug>/.meta/description.md file. It always uses the exercise description from the problem-specifications repo. I even tried uppercase DESCRIPTION.md as well. I'm using Configlet version 3.5.0. Am I missing something? The exercises/<slug>/.meta/HINTS.md file is getting picked up fine. Also, the linter shows no errors.

[snahor]

@bdw429s AFAIK, configlet works only with problem-specifications.

[Insti]

You should be using the description.md from the problem-specifications repository.
(Unless you're trying to implement a track-specific exercise which I would recommend against at this point.)

[tleen]

It always uses the exercise description from the problem-specifications repo. I even tried uppercase DESCRIPTION.md as well. I'm using Configlet version 3.5.0. Am I missing something? The exercises/<slug>/.meta/HINTS.md file is getting picked up fine.

Known bug: exercism/configlet#65, in short you need both the metadata.yml file and the description.md file in the exercises's .meta/ directory to make it pickup the description.md file. Sorry, I should have mentioned that, it tripped me up for a bit too.

[bdw429s]

configlet works only with problem-specifications.

@snahor Assuming you mean with the problem-specifications repo checked out in the same directory as the track repo, yes I had done that. The configlet will throw an error otherwise :)

You should be using the description.md from the problem-specifications repository.

@Insti Thanks for the advice. I'm aware of that and it's my intent to rely on the existing descriptions. I was merely testing just to ensure I understood the configlet and that it worked the way I thought it did. Sorry, testing is in my blood. I don't believe docs until I've done it myself, and in this case I had good reason to doubt :)

Known bug:

@tleen Ahh, yes! I actually ran across that bug the other day while reading, but I didn't know what it meant at the time. Now it all makes sense. 👍

Thanks all!

[bdw429s]

Is there a human-oriented spec or a doc for the format or expected values in the canonical-data.json files of the problem-specifications repo? I searched the docs repo for all references to that file, but found nothing. I did find the JSON spec here https://github.com/exercism/problem-specifications/blob/master/canonical-schema.json but it doesn't really convey the intent of the properties in the JSON, just the scope of valid values. I also read the readme in that repo which helped some more, but still fell short of showing an example of the JSON data and an actual test it could generate for a given language.

So, making the best guesses I can, I've written a test generator that's now part of my exercise scaffold. It will scaffold out BDD style test suites based on the canonical data JSON that takes into account

1. nested suites (with proper indenting)
2. simple or complex values
3. escapes all meta characters including line breaks to CFML standards so syntax is always valid
4. checks to see if the JSON even exists for that exercise
5. Smart expectation handling for .toBeTrue(), .toBeFalse(), .toBe( 'value' ), etc
6. Tests can be regenerated for an existing exercise at any time

task run taskFile=generateTests :slug=bob
# or all tests
task run taskFile=generateTests :all=true

I'm going through testing random exercises, and my biggest remaining question is what to expect for the names of the parameters for each test that will be passed to the method being tested. The parameter names don't seem to follow any format. Is it safe to simply loop over all the keys in the test case and assume that any keys NOT called description, property, expected, or cases are input to the test method?

Here are my assumptions for the keys I listed that I'm assuming will never be the name of a method parameter under test.

• description - Description of this spec
• property - Name of the method being tested
• expected - The expected return value for the inputs
• cases - A nested struct of cases to be recursively followed
• Anything else - A parameter to pass into the method being tested?

You can see the new test generation code in all of its CFML glory in this commit here:
exercism/cfml@ef2544b

Note, I'm waiting for these pulls to get merged before I start actually re-generating tests for my existing exercises. It's getting a little dicey trying to tiptoe all these changes around open pulls with changes spread across a few branches. Can anyone help me get these merged? It's getting difficult to go back and refactor any code that I've already branched off of.

1. Proposed re-work of CFML exercises Proposed re-work of CFML exercises cfml#26
2. Adding much needed docs Adding much needed docs cfml#27
3. New exercise template and scaffold New exercise template and scaffold cfml#28

[bdw429s]

Here's an example test suite generated by my new CFML-powered CLI test generator for the beer-song exercise.
https://gist.github.com/bdw429s/cce22dcd28acb6eb10bd2085c55ffd21

[bdw429s]

The http://exercism.io/ site seems down right now which brings up another question I've been wondering. Do you guys have a Slack team or something where there is more real-time conversation? I get that we're embracing the whole GitHub thing :) but some of these conversations would be really nice in a threaded Slack channel! I figure someone will mention Gitter. I've used it, but not a fan so far. It's not as nice as Slack.

[rpottsoh]

We are on gitter. Here is the support channel.

[ErikSchierboom]

Is there a human-oriented spec or a doc for the format or expected values in the canonical-data.json files of the problem-specifications repo?

There is not much, but there is some information in https://github.com/exercism/problem-specifications/blob/master/README.md. In general your assumptions are correct about the fields you expect in the canonical data.

Is it safe to simply loop over all the keys in the test case and assume that any keys NOT called description, property, expected, or cases are input to the test method?

That is how I do it, and with 40-odd test generators created, there was only one case where there was an extra, unused input field.

[bdw429s]

Excellent. and thanks @ErikSchierboom. I've already added support in my test generator to handle throwing exceptions tonight. I'm on my 10th exercise right now and so far the tests seem to be generating fine. It's so nice to see them go from red to green as I implement each solution 👍

[bdw429s]

OK, here's 10 more pulls. Each one is a new exercise bringing the ColdFusion track to 12 total exercises now. I'm still not sure how these are all going to merge since they all touch the config.json file. I have a feeling only the first one will actually merged without conflicts...

exercism/cfml#39
exercism/cfml#38
exercism/cfml#37
exercism/cfml#36
exercism/cfml#35
exercism/cfml#34
exercism/cfml#33
exercism/cfml#32
exercism/cfml#31
exercism/cfml#30

What's next?
How many more exercises does ColdFusion need to launch?
What other information or setup is missing?
😄

[kotp]

http://exercism.io/languages/coldfusion/todo shows what is not yet implemented for exercises.

[bdw429s]

Thanks @kotp , but to be clear I wasn't asking what exercises weren't implemented yet in CF. When I started resurrecting the ColdFusion track there were basically no exercises implemented at all! So, obviously, they all need to be implemented. I was asking more about what meta tasks needed to happen to actually launch the track and what number of exercises needed to be present.

As of last night, I have implemented 17 of the ColdFusion exercises and they are all sitting in pull requests (one apiece) waiting to be merged.

[tleen]

Not sure there is a defined number. I think you have plenty to start.

[kotp]

Those answers should be answered in issues... let me check. It appears like you have enough exercises, according to this issue so that is completed.

As to what has been done to answer the other questions... Peek at this issue to get some hints. I realize this is an older repository, so some of the guides may not have been placed here, as they may not have been in place.

These questions may be more appropriate in the track repository itself. Flag @kytrinyx and I am sure she has some issues that are templated to place in there to hopefully make this process a bit more structured.

[bdw429s]

Thanks for the additional information @kotp . There is a track issue for the ColdFusion launch here and Katrina is already a part of that conversation.

The biggest problem right now is simply that Katrina is out for a few days and no one else has commit rights to that repo. I'm just looking to get as much done as I can so everything is lined up when she gets back.

[kotp]

I feel you. I just checked, I don't have rights there either. And the track isn't active, if I guess correctly, so currently few candidates for co-maintainers for you... the egg and chicken problem. It is very cool that you are involved in that company... so the chicken and egg problem may not be much of a problem. Just gotta get someone else involved in your company excited about Exercism. :) Then it is will likely be a smoother process for you in that track.

[tleen]

@bdw429s once you get everything committed and people can start trying out the track I'm sure you will get feedback. Work begets work. 😄

[bdw429s]

@kotp Actually, I've been getting some people on board already. I got a good reaction to some requests on Twitter for help plus I've been talking to several fellow CFers and corworkers, showing them how it works and asking them to help contribute stuff. Honestly, I would have probably had people adding exercises by now if everything wasn't held up in the branches. It would be quite a pain for people to have to fork my fork, branch my branches, and send me pull so I could send them on to the main repo shudder. Once we get this in, I think I'll be able to rope in some people to help. As an open source maintainer, I already spend quite a bit of time online providing support for people. Like I mentioned above, we also have a 2.2k person CFML Slack team that will be a good place for students to get mentorship as well.

Work begets work

Let's hope so, @tleen :) My goal for years has been to show the world what a modern language CFML can be! I'm excited for the idea of Exercism funneling new people into the CF ecosystem.

[bdw429s]

After the site build ran today, the ColdFusion track is now live! Thanks to everyone who helped me get it going.
http://exercism.io/languages/coldfusion/about

[tleen]

@bdw429s great work I'm excited to give it a shot.

Something you may consider doing while the track launch is fresh in your mind would be to contribute a bit to the track launch guide. Even if it is just to verify that the docs match your experience.

Congrats on the launch!

[bdw429s]

In case anyone wants to waste 8 minutes of their life, here's a screencast I made today to help get ColdFusion devs using Exercism. I'll have a followup video that shows them how to contribute new exercises.

https://youtu.be/jxs0G9nMfxI

And with this, I'll go ahead and close this issue. I think it's lived a long and prosperous life and served its purpose.

[Insti]

This video is a great intro to Exercism even if you're not using ColdFusion.