jaccarmac / pharo-smalltalk

Exercism Pharo Track

This project is for creating and supporting Exercism exercises for Pharo Smalltalk.

The Pharo Smalltalk exercism track is active and can be accessed here.

If you'd like to help out with testing please sign up for the track using the link above, and review the setup documentation.

Currently we have limited mentor support, so when testing you many need to switch to independent mode if you can't get a timely response. If you need to restart testing, you should "leave" the track then rejoin it.

If you want to help out with development, see below.

Development Setup

This repository is for the development of Exercism exercises running in the Pharo Smalltalk programming environment. It is expected that you are already familiar with development in Pharo and its use of Iceberg Git. If you are new to Pharo or Exercism, consider using Exercism to learn Pharo, so you can then help contribute in the future.

To help with development, you first need to ensure that you have a complete exercism development environment and have installed:

1. the exercism command line interface and configured it to point to somewhere sensible for development (e.g. exercism configure -w ~/development/exercism)
2. the Exercism configlet linter/generator
3. the exercism/pharo repo, as a staging repository to which you will generate exercises and assets to check-in (separately from coding in pharo). I suggest calling it something like ~/development/exercism/pharo-staging to avoid any confusion (note: it can reside anywhere)
4. (Optionally) cloned the exercism/problem specifications repo in a subdirectory of the exercism workspace configured above (this repo was used to generate exercise readme.md files, and is a reference to the suggested tests)

Next setup a Pharo environment for creating the actual coding examples. You need to load a development exercism baseline:

1. Use PharoLauncher to create a fresh 7.0 (stable) development image, and launch it (you can also use zerconf if you are familiar with it)
2. Fork https://exercism/pharo-smalltalk on github
3. Clone https://<your id>/pharo-smalltalk as a GitHub project and specify <your id> as the owner name, pharo-smalltalk as the project name
4. Install the Metacello baseline dev (not the default) in Iceberg using the Metacello context menu. (e.g. right click on the "pharo-smalltalk" project you just cloned, and select the second option in the Metacello menu, and type dev)

If you have any TIMEOUT problems refer to the user installation instructions,

Contributing

We are keen to improve this track and show developers a different way of thinking about coding! 🎉

Please read how to get involved in an Exercism track and also be sure to read the Exercism Code of Conduct.

We welcome pull requests of all kinds. No contribution is too small, particularly those that provide fixes and improvements to existing exercises. Note that this track's exercises must conform to the Exercism-wide standards, but if you're unsure about how to make a change, then open a GitHub issue, and we'll discuss it.

Completing an Exercise

While there many ways to help, by far the easiest and most useful contribution is to complete a solution for any of the currently "open" exercise.

• Ensure your image is caught up to the exercism/pharo-smalltalk master (and push any changes back to your fork)

• The exercises are all TestCases that been automatically generated from the aforementioned problem-specifications repository. You will find them as subclasses of ExercismTest in the ExercismWIP package.

• Once you have selected an Exercise you want to work on, create an Issue in Github specifying "Convert Exercise ". This will let others know you are working on one, and will also form a basis for your later pull request

• Each WIP exercise already has the problem description in its class comment, and you run its tests and TDD a solution (in the debugger if you run the first test by itself).

• You may need to adjust the test if it's not idiomatic Smalltalk (our generator is pretty basic - however this said, some corrections might be appropriate as PR's back to the upstream problem-specification text)

• Update the exercise meta data on the class side of the exercise by overriding the #exercise method and filling in a difficlty, topics etc. You should also fill in some Hint text in the Test comment tab (at the bottom - by replacing the text TBD)

• Update the package of the chosen example to Exercism (i.e. move it out of the WIP package)

• Create a new branch in Iceberg with the name of the exercise you chose (you can use the Iceberg tool for this, and enter your issue number from above)

• Before submitting your pull request, Run all the tests for the Pharo exercises and ensure they all pass

• Now get your solution reviewed by pushing your branch to your fork and then creating a PR on exercism/pharo-Smalltalk

• follow your PR and answer any ensuing questions

• finally submit any adjustments and a maintainer will run the generator to create the Exercism assets (via configlet) and commit the final solution so it appears on the site

Conventions

• We use SUnit (the original xUnit libary) and no additional 3rd-party-frameworks for exercises.
• For consistency, we use the test parameter order: self assert: actual equals: expected

Testing

At the most basic level, Exercism is all about the tests and testing with test suites.

Pharo exercism exercises are organised into sub-packages, which each contain a TestCase that must be compatible with SUunit.

To test an exercise run it from the built-in test runner by clicking on the test orb. The orb will turn green if the tests are successful, or orange or red if their are any failures or errors respectively. Alternatively you can run tests manually in the playground by evaluating:

<ExerciseName>Test suite run. "single exercise"

AllExercismTests suite run. "all exercises"

To test in a non-development image, you should follow the user installation steps. If you are using that image to test subsequent development baselines - you may need to delete the following development directories to ensure you get the latest code: ./pharo/pharo-local/iceberg, ./pharo/pharo-local/package-cache

Coding Style

The code in this repository should follow Pharo with style conventions wherever possible. You can also refer to the more generic Smalltalk with style as well.

You should also make use of the built-in code formatter (meta-t FO in the editor) when creating exercises, as well as the code critques.

Breaking Changes

If you plan to make significant or breaking changes, please open an issue so we can discuss it before merging. If this discussion is relevant to more than just the Pharo track, please also open an issue in exercism/discussions.

Publishing A Completed Exercise (Maintainers)

When an exercise has been reviewed and is ready to put on the site you need to follow some extra steps.

1. Clone a copy of the repository into a staging location (a directory without any special characters due to issue 154)
2. Right click on the exercism Package and choose "Generate exercise meta data", this will generate exercise meta data in your seperate staging location
3. Commit the generated changes into the exercise branch so they will appear with the new exerise

Contributing a New Exercise

If you have an interesting idea, refer to the documentation about adding new exercises.

Note that:

• Each exercise must stand on its own. Do not reference files outside the exercise directory. They will not be included when the user fetches the exercise.
• Exercises must conform to the Exercism-wide standards.
• Exercises should only use the Pharo core libraries.
• Each exercise should be:
  • stored in a sub-project of Exercism named Exercism-<ExerciseName>
  • have a TestCase named <ExerciseName>Tests (in CamelCase) and an example solution named <ExerciseName>
  • the TestCase should have a class comment in markdown format that describes the exercise. This text is also used to generate a README.md file.
• Do not commit any configuration files or directories inside the exercise (this may be reviewed for future exercises, let us know if it becomes a problem)
• Be sure to generate a new UUID for the exercise using the Exercism configlet, and add it to a new exercise entry in the config.json file.

Submitting a Pull Request

Pull requests should be focused on a single exercise, issue, or conceptually cohesive change. Refer to Exercism's pull request guidelines for more detail.

Acknowledgements

Thanks to the Pharo team for all their dedication in building a modern open source Smalltalk.