Launch Checklist

[kytrinyx]

Launch Checklist

Step 0: Prep the Repo (@kytrinyx)

• Create the repository
• Create starter issues
• Turn on Travis CI for the track

Step 1: Implement Exercises

• Implement at least 10 problems

See the contributing guide for the details about the format of an exercise.

The short version is:

• a test suite
• an example solution, named with example (case-insensitive) in the filename
• a section in the "exercises" key of the config.json file with the slug, topics, and difficulty level.

The topics can be an empty list, and the difficulty level is from 1 to 10, and can default to 1 until we know more about the exercises.

"exercises": [
  {
    "slug": "hello-world" ,
    "difficulty": 1,
    "topics": []
  }
]

Step 2: Add the Track to Exercism (@kytrinyx)

• Add R as a submodule in trackler
• Update x-api and deploy

This means that it will show up on http://exercism.io/languages and http://exercism.io/languages/r

Step 3: Make the Track Ready for Launch

• Define test_pattern in config.json
• Add a language icon or logo + attribution
• Write documentation
• Find track mentors
• Add track mentors on the site (@kytrinyx)

test_pattern

The exercism.io website links to the exercise implementations, so it needs to know how to recognize the filename(s) for the test suite.

The "test_pattern" value in the config.json file should be a string that can be compiled as a regular expression, and which will match on the file or files that comprise the test suite of an exercise.

If the test filenames contain the word "test" (case insensitive) then the "test_pattern" key can be deleted.

Language Icon and Attribution

We try to create a language icon that has the exercism colors, and is recognizably similar to the language icon. Sometimes this isn't possible due to copyright issues.

The Exercism colors are:

• #D81D4E (pink)
• #212121 (charcoal)

The icon is used throughout the site in order to identify the language track, and to identify code that has been submitted to that track.

See http://exercism.io/languages for all the existing icons.

Icon

If image assets are not your strong suit, just find a reasonable image to start from, along with the information about the licensing, and we'll figure out the colorization thing (I've written some scripts to help me do this part).

The logo should be named icon.png and live under img/ in this repository. If you know how, go ahead and make an SVG as well.

Attribution

The attribution goes in the README.md file.

If the icon we have based this on is not in the public domain, we need to provide information about license and provenance. If we require permission to use and/or change the icon, then we need to obtain that permission before we can use it.

Documentation

The documentation is used in the http://exercism.io/languages/r section to help people get started with the track.

The files live in the docs/ directory here in this repository, and gets served to the site via the x-api. It should contain at minimum:

• INSTALLATION.md - about how to get the language set up locally.
• TESTS.md - about how to run the tests for the exercises.

Some nice to haves:

• ABOUT.md - a short, friendly blurb about the language. What types of problems does it solve really well? What is it typically used for?
• LEARNING.md - a few notes about where people might want to go to learn the language from scratch.
• RESOURCES.md - references and other useful resources.

Find Track Mentors

Usually in order to see someone's solution you have to have submitted the exercise yourself. Track mentors can access all of the solutions in a given language. Track mentors can therefore help review solutions that people submit on the website in the beginning when few people have submitted solutions to exercises.

Ideally we should have a handful of people who are willing to check Exercism regularly to give people feedback, in order to start the track off on the right note.

The first track mentor needs to be added manually by @kytrinyx, but after that there's a section in the account where existing track mentors can invite new ones.

The most successful tracks are where each submission receives feedback quickly, preferably within the first 24 hours.

In addition, the most interesting and useful conversations start when reviewers do not direct users to do specific things, but rather ask questions challenging people to think about different aspects of their solution, or explore aspects of the language.

Referencing existing blog posts and style guides seems to work well when making specific recommendations.

Prepare for Open Source Contributions

Once the track is live and active, it will often get new contributions.

• Read the maintainer documentation
• "Watch" the xr repository
• Find a second maintainer

We've got a few years of experience maintaining language tracks on Exercism. Here's what we have learned:

• Maintaining a Track
• Reviewing a Pull Request

There's more stuff in the contributing guide, as well. We're working on turning that into better, more focused maintainer documentation.

Launch!

• Toggle "active" to true in config.json
• Mention it in the next "Behind the Scenes" newsletter (@kytrinyx)

[jonboiser]

Thanks to some community contributions, we have got past the 10 problem mark. Some of the other steps might be done already, I'll see what's still TODO in the next few days.

[jonmcalder]

As far as I'm aware, we are already most of the way there, and some of the outstanding to-do's can be marked complete (see below).

To-do's:

• Define test_pattern in config.json (Done)
  The test files are all named test_<exercise-name>.R by convention, so the "test_pattern" key is not needed.
• Write documentation (Done?)
  Not sure what documentation in particular this is referring to, but the docs/ directory seems to have the bases covered (about, installation, learning, resources and tests), and track_hints.MD was updated in Move '/docs/SETUP.md' to '/SETUP.md' and '/exercises/TRACK_HINTS.md' … #34. Am I missing anything?
• Find track mentors (Still to do)
  I'm happy to help and will try invite a few others too.
• Add track mentors on the site (@kytrinyx) (Still to do)
  Could you add me please @kytrinyx?
• Read the maintainer documentation (Done)
• "Watch" the xr repository (Done)
• Find a second maintainer (Still to do)
  I'm keen to come on board as a second maintainer.

The one other thing which doesn't seem to have been mentioned explicitly anywhere on the above to-do list is the ordering of exercises. So far these have just been added sequentially as they were contributed. Since all of the exercises so far are common, as a start it probably makes sense to base the ordering for this track on the existing orderings of these exercises within other language tracks.

I'm happy to review these and do a pull request with suggested re-ordering of exercises, but I think it makes sense to first merge in the outstanding pull requests #31 and #39 (which contain more exercises) so that we can re-order them all in one go.

[kytrinyx]

@jonmcalder I thought I invited you to be a co-maintainer on this track, but I must not have! I've done so now. 🌻

Not sure what documentation in particular this is referring to, but the docs/ directory seems to have the bases covered

Awesome, those are the docs/ we're talking about.

• Add track mentors on the site
  Could you add me please?

Yepp, done!

The one other thing which doesn't seem to have been mentioned explicitly anywhere on the above to-do list is the ordering of exercises.

Huh. Yeah, that's a good point. We don't have good documentation about this anywhere. I've opened an issue in the docs repo to ask that we document it properly (exercism/docs#8), and I've opened a small PR to help bridge the gap meanwhile (exercism/generic-track#18).

I'm happy to review these and do a pull request with suggested re-ordering of exercises, but I think it makes sense to first merge in the outstanding pull requests

Yepp, agreed. Go for it!

[jonmcalder]

Ok cool - thanks!

Glad that my feedback here has helped contribute to the plugging of general documentation gaps - thanks for being on the ball with that. I'm still relatively new to Exercism, but I'm starting to get a feel for things so I'm sure in future I'll have a better sense for when and where to feed these sorts of things upstream into other Exercism repo's and discussions etc.

[kytrinyx]

I'm still relatively new to Exercism

Yeah, when you're new to the project it's nearly impossible to know what should be fixed where.

[katrinleinweber]

Some updated hyperlinks: porting, maintaining, reviewing

[jonmcalder]

@kytrinyx I think the R track can now be toggled to active on the site. In fact, based on the above checklist we have actually been ready for quite a while now.

FWIW, we're up to 25 exercises - and I have another 5 (almost complete) exercises in the wings which we'll incorporate fairly soon I'm sure. The only potential issue I see is that for now it's just @katrinleinweber and I. I know you've spoken of 3+ active maintainers and mentors being the magic threshold for a healthy track (and I'd like to see that happen), but the 2 of us are pretty involved and should at the very least have things well covered from a maintenance point of view.

I know we're all also about to head into the testing phase for nextercism in the next few days (the R track will be fully ready for that once we merge in #69), but I assume that isn't an issue?

[kytrinyx]

@jonmcalder How exciting. Yes, let's turn it on today!

I don't think 2 maintainers is a problem while both are active, it only becomes risky as soon as things happen—international move, new job, new baby, ... the usual :-)

Since we have the nextercism config values for exercises, everything else is optional. Once we launch the beta you'll be able to click around and see what you want to tweak based on it, and you'll have several weeks to get it right and tweaked.

This is looking so great!

[katrinleinweber]

Thanks! Actually, a new job is happening for me, but in an environment that seems FLOSS- & R-friendly :-)

[kytrinyx]

Thanks! Actually, a new job is happening for me, but in an environment that seems FLOSS- & R-friendly :-)

That's fantastic. Congrats on the new gig! See if they're up for making https://opensourcefriday.com/ official :)