Launch tracking

[kytrinyx]

Edit this issue to keep track of the tasks you're working on towards launch.

We have a rough guide for how to launch a track, which is a good starting point;
please ask if you have any questions or if anything is confusing!
https://github.com/exercism/docs/blob/master/language-tracks/launch/README.md

[samWson]

Pharo Launch Tracking

An Introduction

Pharo is a modern implementation of the Smalltalk programming language. This issue will keep track of the tasks required for launching the Pharo track on Exercism.

First Decisions

So far I am the only person maintaining this language track. Here are the choices I have made for the Pharo track and the reason why I made them. Out of all the dialects the biggest factor in choosing Pharo is that it is the one I am most confident in being able to maintain a language track for, as I have the most experience in it. I'm happy to hear anyone else's opinion on this choice.

Why Pharo over other Smalltalk dialects?

There are many Smalltalk dialects, both proprietary and open source. From the perspective of new programmers I want the minimum barrier to entry for people to get programming with Smalltalk as soon as possible. The best choices in my opinion are the open source dialects Squeak and Pharo. Both are actively maintained and have active communities. Both have implementations for Windows, MacOS, and Linux. The points that push Pharo as the choice ahead of Squeak for me are:

• Pharo's excellent collection of free ebooks for learning
• The Pharo launcher tool which makes managing Smalltalk images easy
• Thinking in terms of following on after being a beginner, Pharo's wider selection of built in classes

There may be enough similarity between Squeak and Pharo that one could do the track exercises in Squeak and still submit them. Pharo was forked from Squeak and both include the SUnit test framework.

Challenges

One challenge we face is that Smalltalk programming is not done in text files. Smalltalk has the concept of an image. An image is a snapshot of a system of objects at a point in time. An image is a Smalltalk program. A new image downloaded for a particular Smalltalk will typically contain development tools, and class libraries. All programming is done at runtime while the program (image) is running.

The challenge is how to get the test cases for an exercise downloaded to a computer then incorporated into an image, and how to get a solution out of an image and uploaded to Exercism. Pharo has several ways of sharing code. Pharo can file out code to a text file e.g. a solution could be written in a class in the image, then the class could be filed out and uploaded to Exercism. The downside to this is that there is some noise in the filed out code that would need to be removed and formatted to make it suitable for reading in a single file on Exercism. Another option is to use Pharo's git client tool called Iceberg. Unfortunately I've personally had a miserable time trying to get Iceberg to work. Reaching out to the community may help here. Iceberg is being used for Pharo development so it must be up to the task.

Even though I proposed this language track and I am happy to be its maintainer, I had no idea how we will overcome these challenges when I first made the proposal. I will push this as far as possible until we succeed, or until we stall on insurmountable challenges, in which case we will have learned an awful lot anyway.

To do

There are many tasks to be done to get this language track launched. More can be added as they are discovered.

• Start implementing the first exercise
• Implement the second exercise
• Figure out just how we are going to get Smalltalk code uploaded and downloaded from Exercism Upload Smalltalk solution to Exercism #6
• See if CI tools can be used meaningfully to help maintain this track
• Write contributing documentation
• Decide on the next 10 exercises to implement and open issues for each one
• Put the call out for contributors to help get the track launched
• Prepare the track landing page
• Prepare user facing documentation
• Find mentors

[samWson]

Here is a challenge we are going to have to overcome. Almost all modern programming is done in text files. In Smalltalk all programming is done at run time in an image. When not at run time an image is a snapshot of the state of a Smalltalk program, all the objects it contains. Practically speaking, during development this is the IDE plus whatever code you have written.

If we keep with the current Exercism convention of downloading exercises and uploading solutions as text files, then we should probably use the Smalltalk feature of filing out code. This lets you output into a text file single methods, entire classes, or whole categories/packages of code into a text file. These text files are able to be shared and filed into another image. The files are not intended for editing code, rather they are for machines to read. As a result they do have a bit of noise accompanying the code we are interested in.

The example below is a sample solution for the Hello, World! exercise. Note that you do not view code in Smalltalk as laid out in this text file. Viewing code in the Smalltalk IDE is more like browsing a database of methods and classes. You see things one at a time.

Everything is in a category (or package in Pharo) called HelloWorld. There are two classes. HelloWorld is the solution with the method hello. HelloWorldTest is the test case with the method testHello. Exclamation marks or bangs ! seem to be used to separate the units of code from each other (class declarations, and individual methods). There is some additional meta data inside double bangs !!. Any bangs inside strings seem to be escaped with another bang.

Object subclass: #HelloWorld
	instanceVariableNames: ''
	classVariableNames: ''
	poolDictionaries: ''
	category: 'HelloWorld'!

!HelloWorld methodsFor: 'greetings' stamp: 'SamuelWilson 6/13/2018 20:51'!
hello
	^ 'Hello, World!!'.! !


TestCase subclass: #HelloWorldTest
	instanceVariableNames: ''
	classVariableNames: ''
	poolDictionaries: ''
	category: 'HelloWorld'!

!HelloWorldTest methodsFor: 'tests' stamp: 'SamuelWilson 6/13/2018 20:48'!
testHello
	| greeter |
	greeter := HelloWorld new.
	
	self assert: greeter hello equals: 'Hello, World!!'.! !

I think there is no problem with having files like this inside a users exercism/smalltalk/ directory, you can see it properly in the Smalltalk IDE and the file could still be submitted using the Exercism command line tool. For displaying on the Exercism website, I would like to see the noise and meta data stripped out. Instead we will just see a neat display of a class declaration at the top with the methods underneath. Given that these files are intended to be read by machines, I don't think this should be too much trouble. Perhaps a shell script running something like sed. I'd rather this filtering stage be at the Exercism end of things instead of burdening beginners with this extra task.

Lastly the default directory for the file out action is rather deeply buried in the same directory as the Pharo image, and hard to find if you don't know what you are looking for. I'm going to see if this default location can be changed. I'd like to also turn it into a simple first step on setting up a Pharo environment. Smalltalk is great where something like this could just be a small code snippet that you can copy, paste, and execute in the IDE the very first time you install Pharo. Again the point is to keep things as simple as possible for beginners.

Alternatively, Pharo's Git client Iceberg could be another option, as Git is for versioning text files. I'll need to look into that more.

This problem is the crux of issue #6.

Comment if you have suggestions, problems, or encouragement.

[kytrinyx]

we should probably use the Smalltalk feature of filing out code.

Yes, I can't think of any other way to make this work with the same mechanism as the rest of the tracks. It pains me a little bit to do something that is so un-native to the basic experience of Smalltalk, but I think that the upside of being able to lean on all the existing mechanisms is worth it.

displaying on the Exercism website, I would like to see the noise and meta data stripped out.

I agree; we shouldn't burden anyone with the added mental overhead of dealing with that.

I'd rather this filtering stage be at the Exercism end of things instead of burdening beginners with this extra task.

Right--we definitely don't want to put that on beginners. I'd be open to having custom logic in the command-line client that parses and strips that out on submit. The one thing that I want to make sure we think through carefully is how we can optimize for both:

• handling this transparently for the people doing the exercises
• making it possible for mentors to download a solution and file it into the image and look at it locally

If we strip out the metadata it might be hard to put it back. Another option would be to have the submit function submit two files, one which would be hidden (which keeps all the metadata), and one which would be displayed on the site (which strips it out). That way when you download a solution, you could file in the original, unchanged file.

This is going to be fun!

[SergeStinckwich]

@samWson I support also your Pharo choice. Maybe you can join Pharo Discord : http://discord.gg/Sj2rhxn in order to attract more people to help you.

[bencoman]

You might consider "Tonel", a new human-friendly code-file format introduced by Pharo
https://github.com/pharo-project/pharo/blob/development/src/Morphic-Examples/ClassListExample.class.st

[samWson]

@SergeStinckwich Thanks for the suggestion. I will definitely join the Pharo Discord. I'm sure I'll be needing the help in the near future.

@bencoman I hadn't heard of Tonel before, thanks for letting me know. I think it looks more readable than filed out code. I've just done some very quick research on it. It looks like it can be used with Iceberg, or Monticello? Can it also be used as a format for filing out code? I'm looking for a solution that has as few complex steps as possible, to keep things simple for beginners.

[macta]

I second Tonel - I often use a git client on my iPhone to make simple experimental changes to my side-Pharo projects and then see GitLab build and deploy them.

[samWson]

@macta @bencoman you two should have received invites to be collaborators for this repo by now. Let me know if you haven't received anything yet.

[kytrinyx]

@samWson @macta @bencoman I wanted to check in with you to figure out where we're falling down in supporting you get the Pharo track organized.

The first thing on my list is to sort out the documentation for launching a new track. I need to make sure we've deleted all the references to the old site (there aren't a whole lot of things that aren't relevant), and also clarify all the steps for the new site.

The second thing is that I want to make sure that we're providing a decent beta setup for you so you can test this on the live site.

Are there any specific things on your mind where stuff has been confusing/blocking?

[kytrinyx]

I've added Pharo to the site in "inactive" mode: https://exercism.io/tracks/pharo

[samWson]

@kytrinyx Our biggest challenge seems to be making a solution where we can fit the Smalltalk way of doing everything in a live image into a world that expects text files. I'm happy to say we have a solution for this in progress. It's just small steps at the moment as we feel our way through.

The initial documentation for getting a track started was helpful in guiding the first few steps e.g. early decisions, and exercises. The custom solution above seems to have consumed most of our time. The others can probably tell you more from their point of view especially when it comes to things like CI.

Other than having to come up with custom tools for this track, the only major problem was making @bencoman and @macta contributors. I take it you were away or just unable to respond for some time? Unfortunate, but that problem is solved now. Both of them have been invaluable as they have come up with results that were beyond my skills and have greatly increase the pace of development.

Thanks for checking up with us.

[macta]

@kytrinyx thanks for getting us back into inactive, its helpful to now see how the docs hang together (some improvements currently in review).

How do we get the logo to show up on the tracks/pharo rendering (is that what #12 is about?)

[macta]

@kytrinyx with regards to support - I think we’ve now got a decent understanding of how things work but translating the concepts to something a bit different like Smalltalk has been tricky without a clear summary of what means what. I think something you can read that would glue it all together for newcomers would be very helpful. Particularly when you seem to rely on convention more than configuration e.g.

The docs (the ones in uppercase in /docs) are what appear on you track landing page, and your snippet is what appears as a language example (but it should be max X lines to avoid scrolling). The logo in the top corner is in ../? And you need to get it approved (checking it in doesn’t just work?). I’m still a bit unclear on some of the go templating stuff which looks like it can append stuff to exercise readme’s automatically.

The config.json also needs more docs - the stuff you mentioned about kebab case etc. Also many other tracks seem to have many undocumented attributes in theirs - maybe they are all v1 stuff?

It’s also not clear which are core exercises (is there a list somewhere?) and I’m still not clear on what drives the extra exercises that appear when you complete something (presumably a core one - e.g. in the python track I did hello world and got some, and then did leap and got a few more?).

I’m still not quite clear on how mentoring works - and for a new track do we have to find mentors, and what are they committing too?

With the CI - I worked it out, but I wasn’t sure whether you integrated anything exercism specific - I think you just check if its green, and run the linter.

I think lots of this stuff is scattered around, so I think having something that summarises it and then points you off to the right bits might be enough

[samWson]

@macta @bencoman I'd like to thank you two for all the work you have done so far. Your help has been invaluable. You have made a workable solution that I probably wouldn't have been able to achieve by myself.

@macta You have been making PR's and merging them faster than I can keep up (this is a good thing). The pace of your work is phenomenal. So much in fact that I am having trouble keeping track of our progress. You clearly understand the ins and outs of Exercism and our solution far better than I do.

This has left me at a bit of a loss. I'm unsure as to where I should direct my efforts. The sheer number of issues being opened and closed is bewildering. I'm only giving this project about an hour or so of my free time each night to avoid burning myself out. This has to balance with the rest of my life.

@macta @bencoman I am asking you two what you think I should do that will help move this project along? I could keep track of our epics and stories that need to be put into issues, keeping track of the projects progress. I can do some usability testing of what we have so far. I can do some coding though this takes most of my focus, and as I said the interaction of Exercism and our tools is still largely unknown to me. Let me know where my focus should be at the moment.

[macta]

@samWson there are lots of things to do, once we get it working end to end. Apologies on the fast PR turnaround - normally I would wait for proper reviews so you can spot things (like you already have), however I had a window of opportunity to blast away at the beginning of a holiday - so I've forged on while the iron was hot and I could understand what is happening.

I think we are almost there - I've managed to retrieve solutions, and submit them (kind of) - but there are gotchas in all of this, particularly as exercism v1 to v2 introduced changes with meta files, and also because they are catching up with docs and ways to let people test.

It would be quite handy now, to join the track and try to download a solution within the IDE and then submit a solution (e.g. try it end to end). I think I'm on automatic now so blinded...

We then have to write a ton of exercises and then work out the correct ordering, and the best ways to highlight pharo features.

Also - my code needs proper reviewing, and I'm conscious that it needs refactoring and some proper tests written as its been a big spike - but I felt getting something limping along might allow others to write exercises if we get the flow right.

And heck - I think we're all learning here.

Would be nice to chase the logo - its not appearing yet.

[macta]

@samWson BTW are you on Pharo discord? Would be good to chat realtime - I am also going to be in NewZealand in a few months - might be able to hook up. @bencoman same for Oz.

[bencoman]

On 6 August 2018 at 16:48, Samuel ***@***.***> wrote: @macta <https://github.com/macta> @bencoman <https://github.com/bencoman> I am asking you two what you think I should do that will help move this project along? I could keep track of our epics and stories that need to be put into issues, keeping track of the projects progress. I can do some usability testing of what we have so far. I can do some coding though this takes most of my focus, and as I said the interaction of Exercism and our tools is still largely unknown to me. Let me know where my focus should be at the moment.

I'm also a bit in the same boat (amazed at the progress and a bit out of touch.) To refamiliarise myself I guess I'll start testing the student experience, then the contributor instructions, then look for some exercises to develop.

On 6 August 2018 at 17:50, Tim Mackinnon ***@***.***> wrote: @samWson <https://github.com/samWson> BTW are you on Pharo discord? Would be good to chat realtime - I am also going to be in NewZealand in a few months - might be able to hook

Here is an invite for a channel I created for us to chat >>> https://discord.gg/S9VuxKc Perhaps once the contributor flow is well tested we can advertise for help and get some social interaction around contributing exercises.

[samWson]

I'm on Pharo discord under the same name. I just waved in the chat room.

@macta I'll have a look at #45 since you have already pointed that one out to me. I suggest we make good use of the Assignees feature in issues and pull requests. Then others will know that issues are being dealt with.

I am also going to be in NewZealand in a few months - might be able to hook up.

Ping me in the Pharo discord if your in the Wellington region. Probably the easiest way to get in touch with me.

[samWson]

Just a quick update to all. The exercism/exercism-pharo-tooling repo has been archived. All our tooling is happily able to co-exist along with the exercises in this repo.

[kytrinyx]

I hear you on the lack of documentation. I've consulted with a technical writer / professional docs writer to help me restructure the docs, and I hope that I'll be able to get this more under control in the next few weeks.

[macta]

Just need to find more mentors