First off all, thank you for taking the time to contribute!
- Code of Conduct
- What is the walkthrough?
- How can I help?
- How do I start contributing?
- Submitting Code Changes
Help us keep exercism welcoming. Please read and abide by the Code of Conduct.
Looking at the data, we noticed that a significant number of users have never completed a single exercise on exercism. We believe this is because setting it up isn't easy. This walkthrough aims to solve that.
The goal of the walkthrough is to guide users through the many steps of installing the Exercism command-line client (CLI), which is a prerequisite to doing exercises on the site.
The walkthrough is structured in the following way:
- To prevent users from getting lost, the walkthrough is a step by step guide.
- At the end of each step, the user must be able to confirm whether they've done the step correctly. This should prevent users from installing incomplete packages which may lead to harder troubleshooting in the future.
- When the user encounters a problem during a step, the user should be given steps to self-diagnose or troubleshoot the problem on their own.
You can help by:
- Giving feedback on the walkthrough. In particular:
- Did the instructions match your experience?
- Are any steps confusing?
- Did we miss any steps?
- Writing better instructions. If you have a better way to describe a step in mind, a PR submission would be greatly appreciated.
- Looking through the issues and submitting a patch. We're tracking bugs and upcoming features in this repository's issue tracker.
- Clone the repository.
$ git clone https://github.com/exercism/interactive-cli-walkthrough
- Inside the repository's directory, run the following command:
$ bundle
Each step is written in Markdown and Twee-style. If you haven't used Markdown before, we recommend looking at this tutorial. If you haven't used Twee2 yet, this is the project documentation
Steps should be saved with the *.tw2 file extension.
In order to add a step, you must first add it to the table of contents. The table of contents is the file named table_of_contents.tw2.
To further explain the table of contents' structure, let's take a look at an example:
::StoryIncludes
common/step_1.tw2
common/step_2.tw2
The first line, ::StoryIncludes, is a special command which doesn't need to
be changed.
The consecutive lines tell the table of contents that we have two steps,
common/step_1.tw2 and common/step_2.tw2. These steps are located inside
the common/ directory and have the file names step_1.tw2 and step_2.tw2,
respectively.
If we want to add a third step, step_3.tw2, located inside the mac/
directory, we write the table of contents this way:
::StoryIncludes
common/step_1.tw2
common/step_2.tw2
mac/step_3.tw2
To make it easy to create links between steps, two special commands are available:
::Link Destination
This sets a step's name as Link Destination which is needed in order for the
link command to know what step to link to. This command is placed on the first
line of the file.
[[<Link Text>-><Link Destination>]]
This creates a link with Link Text that links to a step entitled
Link Destination.
In order to add your own images, you'd need to put them within the content/assets folder.
To render the image on the page, this command is used:
The token WALKTHROUGH_ASSETS_PATH is needed as it points to the path of the assets folder.
In order to view your changes, you need to compile the project. Compiling is done by running this command:
$ bundle exec rake compile
Compiling produces a file named compiled.html in the root of the repo. Open this file in your browser and you should see your changes.
If you're a bit lost of how each step links to another, you can generate the walkthrough graph.
This requires Graphviz—follow the instructions for your platform on the Graphviz Download page.
Then run this command:
$ bundle exec rake graph
This produces a file named graph.png. This tool is also helpful to find broken
links between steps.
If you're new to contributing to open source on GitHub, this next section should help you get started. If you get stuck, open an issue to ask us for help and we'll get you sorted out (and improve these instructions).
- Fork and clone.
- Add the upstream interactive-cli-walkthrough repository as a new remote to your clone.
git remote add upstream https://github.com/exercism/interactive-cli-walkthrough.git - Create a new branch
git checkout -b name-of-branch - Commit and push as usual on your branch.
- When you're ready to submit a pull request, rebase your branch onto
the upstream master so that you can resolve any conflicts:
git fetch upstream && git rebase upstream/masterYou may need to push with--forceup to your branch after resolving conflicts. - When you've got everything solved, push up to your branch and send the pull request as usual.
When submitting a pull request, sometimes we'll ask you to make changes before we accept the patch.
Please do not close the first pull request and open a second one with these changes. If you push more commits to a branch that you've opened a pull request for, it automatically updates the pull request.
When the pull request is ready to be merged, you will probably be asked to squash your commits.
As with adding more commits, you do not need to close your pull request and open a new one. If you change the history (rebase, squash, amend), and use git push --force to update the branch on your fork. The pull request points to that branch, not to specific commits.
Here's a guide on how to squash commits in a GitHub pull request.
When submitting a PR, please make sure to include the compiled HTML and the newly generated walkthrough graph.
For more guidance, you are free to peek into how the installation instructions for Mac were written.
In order to parse the files, we've written a custom Twine2 story format called Exercism. It is located within storyFormats/.
The story format code lives in exercism/twine2-story-format.