Launch Checklist
Closed this issue · 7 comments
In order to launch we should:
- Turn on Travis CI for the track (kytrinyx)
- Add MIPS as a submodule in x-api (kytrinyx)
- Implement at least 10 problems
- Write documentation (see below)
- Find a person or (ideally) a handful of people willing to check exercism regularly (daily?) to review solutions
- Add track implementors and other designated code reviewers as mentors to the track. This gives you access to all the solutions in MIPS Assembly whether or not you've submitted the problem to the site. 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.
- Add a language icon or logo (see below) + attribution (in README)
- Toggle
"active"totrueinconfig.json - Mention it in the next "Behind the Scenes" newsletter (kytrinyx)
Documentation
The documentation lives in the docs/ directory here in this repository, and gets served to the site via the x-api. It should contain at minimim:
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.
Logo/Icon
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. See http://exercism.io/languages for all the existing icons.
We're in the process of moving each individual language track icon into the specific language track repository. Putting all the language-specific stuff together makes it easier to manage. In the meanwhile, we need to have everything in two places.
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).
Some icons are the official language logo (tweaked). Where a language doesn't seem to have an official logo, or where the official logo has copyright issues, we just make something up.
exercism.io
The logo should be named mips.png and live in /public/img/tracks/ in the exercism/exercism.io repository.
https://github.com/exercism/exercism.io/tree/master/public/img/tracks
Attribution goes in https://github.com/exercism/exercism.io/blob/master/ATTRIBUTION.md
xmips
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 goes in the README.md file.
Successful Launches
Some tracks have been more successful than others, and I believe the key features of the successful tracks are:
- Each submission receives feedback quickly, preferably within the first 24 hours.
- The code reviews 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.
For more about contributing to language tracks on exercism, check out the Problem API Contributing guide: https://github.com/exercism/x-api/blob/master/CONTRIBUTING.md
@kytrinyx FYI we have 10 problems now. We'll keep adding more over time, but it'd be great to get feedback from users along the way. Also for now Myles and I are happy to check in daily to review solutions. Let me know if you have any suggestions about a language logo :)
That was fast! For the logo if there's nothing obvious you can just make something up. If there is a logo, then check out the licensing on the logo—if it's too complicated, make something up (we did that for Java).
Where things are modifiable with attribution, I try to either use a grayscale version, sometimes adding in some pink. I'm terrible at graphics, and after losing a day of my life trying to figure out how to change colors in images I wrote a script that rewrites PNGs, replacing colors based on hex values passed to the command line interface. https://github.com/kytrinyx/twotone It's not awesome but it will do the job.
The exercism black color is 212121. The pink is D81D4E.
@ozan @quackingduck I've added both of you as track mentors on the MIPS track.
For the logo if there's nothing obvious you can just make something up
Ok done! 😄 8d3defd. Want me to make a PR to add it to exercism/exercism.io too?
Perfect! Yeah, if you would add it to exercism/exercism.io as well... we can launch this today and I'll mention it in tomorrow's newsletter.
I sent out the newsletter this morning. I'll tweet about it when the track goes live (cough softlaunch cough) and then I'll stick it in the newsletter next week.