Skip to content

Latest commit

 

History

History
183 lines (121 loc) · 14.6 KB

CONTRIBUTING.md

File metadata and controls

183 lines (121 loc) · 14.6 KB

Contributing guidelines

If you want to participate on Pharo track development, you should follow instructions below that will help you to start.

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.

Note: Exercism organization has decided to pause Exercism wider community contributions. Pharo track is opted-out from this policy, since our community is rather small (In other words: any Pharo track contributor can still create issues and submit PRs).

Knowledge prerequisites

It is expected that you are already familiar with development in Pharo and its use of Iceberg Git.

Development environment setup

To begin, you need to ensure that you have a complete Exercism development environment and have following artefacts installed:

Pharo image and IDE

You need to have a Pharo development environment (running Pharo image - IDE) for creating the actual coding examples.

  1. Use PharoLauncher to create a fresh 10.0 (stable) development image from Official distributions category, and launch it (you can also use zerconf if you are familiar with it).
  2. Launch your image to test everything runs ok.

Note: If you have any TIMEOUT problems refer to the user installation instructions.

Setup of git repositories

  1. If you haven't done previously, fork https://exercism/pharo-smalltalk on Github.
  2. To clone your fork, evaluate following command in Playground of running Pharo image:
Metacello new
 baseline: 'Exercism';
 repository: 'github://exercism/pharo-smalltalk:main/releases/latest';
 load: 'dev'

This will effectively clone git repository of Pharo track and load Pharo track source code into Pharo image - its development baseline. Local folder with cloned repository will be located in (depending on your Iceberg preferences): <path-to-Pharo-image>/pharo-local/iceberg/<your-id/pharo-smalltalk.

Note: Pharo image sources are synchronized and serialized in *.st files locaded in src sub-folder of aforementioned directory.

  1. Other way to do the same is to clone your fork via CLI: git clone https://github.com/<your id>/pharo-smalltalk as a GitHub project and specify <your id> as the owner name, pharo-smalltalk as the project name.
    Then Install the Metacello baseline dev (not the default) in Iceberg using the Metacello context menu of running Pharo image. (e.g. right click on the "pharo-smalltalk" project you just cloned, and select the second option in the Metacello menu, and type dev)

  2. After loading project to Pharo image, don't forget to Save image changes (menu item Pharo -> Save).

Optional repositories

  1. Alernatively you can git clone https://github.com/exercism/pharo-smalltalk as a staging repository to which you will generate exercises and assets to check-in (separately from coding in Pharo). Note that changes generated by Configlet tool in this repository will need to be copied into your local fork repository. Suggestion is to use something like ~/development/exercism/pharo-staging to avoid any confusion (note: it can reside anywhere). This repository is not needed, you can still generate configlet changes directly in your forked repo (That is synced with your Pharo image), if you are sure, which changes to include in commit.
  2. You can also clone Exercism problem specifications, in case you want to work on Practise exercises from scratch. Put it also in a subdirectory of the exercism workspace configured below (this repo is used to generate exercise readme.md files, and is a reference to the suggested tests).

Note about used repository branches

The main branch is the primary development branch to which is everything merged. If you work on some change in code, create feature branch originated from main and commit your changes there. Once completed, issue PR on github to be merged to main of base rerpository (Exercism/pharo-smalltalk). This branch used to be called master - now deprecated.

Setup of Exercism CLI tools

These tools are needed to interact with Exercism project:

  1. the exercism command line interface and configured it to directory with Exercism exercises development called workspace (e.g. exercism configure -w ~/development/exercism). This could be either path to your local fork repository or (optional) staging repository.
  2. the Exercism configlet linter/generator for generating exercise metadata and running validations. To install Configlet follow instructions in Use in your track paragraph (see bin/fetch-configlet).

Working on Exercism exercises

Exercism organization distinguish between Concept exercises (explaining PL theory) and Practise exercises. Paragraphs below focus just on Practise exercise contribution so far.

Overview

Steps to complete exercise:
1a. Create Practise exercise from scratch (from problem specifications).
1b. Work on solution of existing Practise exercise.
2a. Generate serialized source files of exercise solution to directory and generate exercise metadata.
2b. Adjust project baseline to include newly completed exercise as part of project.
3. Commit changes to your repository fork and publish changes by issing PR.

Workflow to complete Practise exercise

1. Create new Practise exercise

From problem repository

  • If you want to start completely new Practise exercise (step 1a.), you can use problem specification repository and generate test class for given exercise by running: ExercismExerciseGenerator generateFrom: <path-to-problem-specifications/exercises> - this will generate test classes for all exercises in problem specifications repository in ExerciseWIP package.

    Note: You can use menu item in Pharo image for achieving same (World menu -> Exercism -> Generate test cases).

  • More specifically, you can generate test class for specific exercise by: ExercismExerciseGenerator generateExerciseFrom: '<path-to-problem-specifications/exercises/slug-name>' asFileReference.

Result of previous statement will be new <SlugNameTest> (a subclass of ExercismTest) test class with generated test methods in ExerciseWIP package.

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

There is an example of a user defined exercise in the project, see: DieTest. By overriding the method customData, the generator will create the relevant files for you.

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 top level project named Exercism@<ExerciseName>
    • have a TestCase named <ExerciseName>Test (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 UUIDGenerator next, and place that value in the uuid method for the test.

2. Work on existing 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 main (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 difficulty, 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 Exercise@<ExerciseName> (i.e. move it out of the WIP package) - step 1b.

  • 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.

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. This is the original xUnit libary and no additional 3rd-party-frameworks for exercises are needed.

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"

Note: If you want to define your own (non-generated) test case, you can put it to extra protocol of test class.
For consistency, we use the test parameter order: self assert: actual equals: expected it test method.

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

3. Publishing A Completed Exercise

Now when you're done with solution and commits to you local feature branch, you should complete these steps:
Step 2a: Generate source code files for solution and test class by running either:

  • ExercismGenerator generate -> this will generate all souce files of all exercises. It will run generate command of configlet and also re-generates config.json that lists all valid exercises. (Or in World menu choose: "Exercism" -> "Regenerate meta data")

Or:

  • ExercismGenerator generateSourceFilesFor: <Exercise@SlugName> to: <path-to-exercise-repo/exercises> to produce source files just for specific exercise.

    Note that you'd need to run manually:

    • update config.json manually (see ExercismGenerator>>generate for details)
    • configlet sync --docs --filepaths --metadata -uy -e <slug-name> tu update all metadata for specific exercise. See details: Using sync when adding a new exercise

Step 2b: Update Pharo-smalltalk project baseline by adding exercise name in list of BaselineOfExercism>>exercisePackageNames method. This will ensure your exercise to be loaded, when project is loaded including new exercise by Metacello command.

Step 3: Before creating PR, you should check if Exercism artefacts are correct by running CLI command: bin/configlet lint. If everyrting is ok. PR can be created.

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.

  • Now get your solution reviewed by pushing your branch to your fork and then creating a PR on exercism/pharo-Smalltalk. It is important to enable maintainer edits, so we can collaborate with you in your branch
    • follow your PR and answer any ensuing questions
    • finally submit any adjustments and a maintainer will merge your Pull request to appear final solution on the site.

Additional information for maintainers

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.

Acknowledgements

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

Pharo