├── .appends └── .github │ └── labels.yml ├── .github ├── labels.yml └── workflows │ └── sync-labels.yml ├── CODE_OF_CONDUCT.md ├── LICENSE ├── README.md ├── about ├── README.md ├── architecture.md ├── conception │ ├── README.md │ ├── code-review.md │ ├── emotional-stages │ │ ├── README.md │ │ ├── feelings-code-review.png │ │ ├── feelings-learning-to-code.png │ │ ├── feelings-trying-something-new.png │ │ └── user-journey.pdf │ ├── goals.md │ └── progression.md ├── glossary.md ├── goal-of-exercism.md ├── roadmap.md └── scope-of-a-track.md ├── contributing-to-language-tracks └── README.md ├── contributing ├── filing-a-bug-report.md ├── git-basics.md ├── providing-feedback.md └── pull-request-guidelines.md ├── finding-your-way.md ├── language-tracks ├── README.md ├── configuration │ ├── README.md │ ├── configlet.md │ ├── exercises.md │ └── track.md ├── documentation │ ├── for-consumers.md │ ├── for-contributors.md │ └── introductory-copy.md ├── exercises │ ├── README.md │ ├── anatomy │ │ ├── README.md │ │ ├── readmes.md │ │ ├── reference-solution.md │ │ └── test-suites.md │ └── versioning.md └── launch │ ├── README.md │ ├── beta.md │ ├── finding-mentors.md │ ├── first-exercise.md │ ├── landing-page.md │ ├── open-issues.md │ ├── preview-mode.md │ └── tooling-and-ci.md ├── maintaining-a-track ├── README.md ├── bootstrap-new-track.md ├── inviting-new-maintainers.md ├── maintainer-configuration.md ├── regenerating-exercise-readmes.md └── starting-new-track.md └── you-can-help ├── implement-an-exercise-from-specification.md ├── improve-exercise-metadata.md ├── make-up-new-exercises.md ├── review-pull-requests.md ├── triage-issues.md └── update-exercise-test-suites.md /.appends/.github/labels.yml: -------------------------------------------------------------------------------- 1 | # ----------------------------------------------------------------------------------------- # 2 | # These are the repository-specific labels that augment the Exercise-wide labels defined in # 3 | # https://github.com/exercism/org-wide-files/blob/main/global-files/.github/labels.yml. # 4 | # ----------------------------------------------------------------------------------------- # 5 | 6 | - name: "good first patch" 7 | description: "" 8 | color: "43C59E" 9 | 10 | - name: "invalid" 11 | description: "" 12 | color: "fef2c0" 13 | 14 | - name: "spam" 15 | description: "" 16 | color: "08787a" 17 | 18 | - name: "status/claimed" 19 | description: "" 20 | color: "CEFF1A" 21 | 22 | - name: "status/no-longer-relevant" 23 | description: "" 24 | color: "CEFF1A" 25 | 26 | - name: "status/on-hold" 27 | description: "" 28 | color: "CEFF1A" 29 | 30 | - name: "status/pr-in-progress" 31 | description: "" 32 | color: "CEFF1A" 33 | 34 | - name: "status/up-for-grabs" 35 | description: "" 36 | color: "CEFF1A" 37 | -------------------------------------------------------------------------------- /.github/labels.yml: -------------------------------------------------------------------------------- 1 | # --------------------------------------------------------------- # 2 | # This is an auto-generated file - Do not manually edit this file # 3 | # --------------------------------------------------------------- # 4 | 5 | # This file is automatically generated by concatenating two files: 6 | # 7 | # 1. The Exercism-wide labels: defined in https://github.com/exercism/org-wide-files/blob/main/global-files/.github/labels.yml 8 | # 2. The repository-specific labels: defined in the `.appends/.github/labels.yml` file within this repository. 9 | # 10 | # If any of these two files change, a pull request is automatically created containing a re-generated version of this file. 11 | # Consequently, to change repository-specific labels you should update the `.appends/.github/labels.yml` file and _not_ this file. 12 | # 13 | # When the pull request has been merged, the GitHub labels will be automatically updated by the "Sync labels" workflow. 14 | # This typically takes 5-10 minutes. 15 | 16 | # --------------------------------------------------------------------- # 17 | # These are the Exercism-wide labels which are shared across all repos. # 18 | # --------------------------------------------------------------------- # 19 | 20 | # The following Exercism-wide labels are used to show "tasks" on the website, which will point users to things they can contribute to. 21 | 22 | # The `x:action/` labels describe what sort of work the contributor will be engaged in when working on the issue 23 | - name: "x:action/create" 24 | description: "Work on something from scratch" 25 | color: "ffffff" 26 | 27 | - name: "x:action/fix" 28 | description: "Fix an issue" 29 | color: "ffffff" 30 | 31 | - name: "x:action/improve" 32 | description: "Improve existing functionality/content" 33 | color: "ffffff" 34 | 35 | - name: "x:action/proofread" 36 | description: "Proofread text" 37 | color: "ffffff" 38 | 39 | - name: "x:action/sync" 40 | description: "Sync content with its latest version" 41 | color: "ffffff" 42 | 43 | # The `x:knowledge/` labels describe how much Exercism knowledge is required by the contributor 44 | - name: "x:knowledge/none" 45 | description: "No existing Exercism knowledge required" 46 | color: "ffffff" 47 | 48 | - name: "x:knowledge/elementary" 49 | description: "Little Exercism knowledge required" 50 | color: "ffffff" 51 | 52 | - name: "x:knowledge/intermediate" 53 | description: "Quite a bit of Exercism knowledge required" 54 | color: "ffffff" 55 | 56 | - name: "x:knowledge/advanced" 57 | description: "Comprehensive Exercism knowledge required" 58 | color: "ffffff" 59 | 60 | # The `x:module/` labels indicate what part of Exercism the contributor will be working on 61 | - name: "x:module/analyzer" 62 | description: "Work on Analyzers" 63 | color: "ffffff" 64 | 65 | - name: "x:module/concept" 66 | description: "Work on Concepts" 67 | color: "ffffff" 68 | 69 | - name: "x:module/concept-exercise" 70 | description: "Work on Concept Exercises" 71 | color: "ffffff" 72 | 73 | - name: "x:module/generator" 74 | description: "Work on Exercise generators" 75 | color: "ffffff" 76 | 77 | - name: "x:module/practice-exercise" 78 | description: "Work on Practice Exercises" 79 | color: "ffffff" 80 | 81 | - name: "x:module/representer" 82 | description: "Work on Representers" 83 | color: "ffffff" 84 | 85 | - name: "x:module/test-runner" 86 | description: "Work on Test Runners" 87 | color: "ffffff" 88 | 89 | # The `x:rep/` labels describe the amount of reputation to award 90 | # 91 | # For more information on reputation and how these labels should be used, 92 | # check out https://exercism.org/docs/using/product/reputation 93 | - name: "x:rep/tiny" 94 | description: "Tiny amount of reputation" 95 | color: "ffffff" 96 | 97 | - name: "x:rep/small" 98 | description: "Small amount of reputation" 99 | color: "ffffff" 100 | 101 | - name: "x:rep/medium" 102 | description: "Medium amount of reputation" 103 | color: "ffffff" 104 | 105 | - name: "x:rep/large" 106 | description: "Large amount of reputation" 107 | color: "ffffff" 108 | 109 | - name: "x:rep/massive" 110 | description: "Massive amount of reputation" 111 | color: "ffffff" 112 | 113 | # The `x:size/` labels describe the expected amount of work for a contributor 114 | - name: "x:size/tiny" 115 | description: "Tiny amount of work" 116 | color: "ffffff" 117 | 118 | - name: "x:size/small" 119 | description: "Small amount of work" 120 | color: "ffffff" 121 | 122 | - name: "x:size/medium" 123 | description: "Medium amount of work" 124 | color: "ffffff" 125 | 126 | - name: "x:size/large" 127 | description: "Large amount of work" 128 | color: "ffffff" 129 | 130 | - name: "x:size/massive" 131 | description: "Massive amount of work" 132 | color: "ffffff" 133 | 134 | # The `x:status/` label indicates if there is already someone working on the issue 135 | - name: "x:status/claimed" 136 | description: "Someone is working on this issue" 137 | color: "ffffff" 138 | 139 | # The `x:type/` labels describe what type of work the contributor will be engaged in 140 | - name: "x:type/ci" 141 | description: "Work on Continuous Integration (e.g. GitHub Actions workflows)" 142 | color: "ffffff" 143 | 144 | - name: "x:type/coding" 145 | description: "Write code that is not student-facing content (e.g. test-runners, generators, but not exercises)" 146 | color: "ffffff" 147 | 148 | - name: "x:type/content" 149 | description: "Work on content (e.g. exercises, concepts)" 150 | color: "ffffff" 151 | 152 | - name: "x:type/docker" 153 | description: "Work on Dockerfiles" 154 | color: "ffffff" 155 | 156 | - name: "x:type/docs" 157 | description: "Work on Documentation" 158 | color: "ffffff" 159 | 160 | # This label can be added to accept PRs as part of Hacktoberfest 161 | - name: "hacktoberfest-accepted" 162 | description: "Make this PR count for hacktoberfest" 163 | color: "ff7518" 164 | 165 | # This Exercism-wide label is added to all automatically created pull requests that help migrate/prepare a track for Exercism v3 166 | - name: "v3-migration 🤖" 167 | description: "Preparing for Exercism v3" 168 | color: "e99695" 169 | 170 | # ----------------------------------------------------------------------------------------- # 171 | # These are the repository-specific labels that augment the Exercise-wide labels defined in # 172 | # https://github.com/exercism/org-wide-files/blob/main/global-files/.github/labels.yml. # 173 | # ----------------------------------------------------------------------------------------- # 174 | 175 | - name: "good first patch" 176 | description: "" 177 | color: "43C59E" 178 | 179 | - name: "invalid" 180 | description: "" 181 | color: "fef2c0" 182 | 183 | - name: "spam" 184 | description: "" 185 | color: "08787a" 186 | 187 | - name: "status/claimed" 188 | description: "" 189 | color: "CEFF1A" 190 | 191 | - name: "status/no-longer-relevant" 192 | description: "" 193 | color: "CEFF1A" 194 | 195 | - name: "status/on-hold" 196 | description: "" 197 | color: "CEFF1A" 198 | 199 | - name: "status/pr-in-progress" 200 | description: "" 201 | color: "CEFF1A" 202 | 203 | - name: "status/up-for-grabs" 204 | description: "" 205 | color: "CEFF1A" 206 | -------------------------------------------------------------------------------- /.github/workflows/sync-labels.yml: -------------------------------------------------------------------------------- 1 | name: Tools 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | paths: 8 | - .github/labels.yml 9 | - .github/workflows/sync-labels.yml 10 | workflow_dispatch: 11 | schedule: 12 | - cron: 0 0 1 * * # First day of each month 13 | 14 | permissions: 15 | issues: write 16 | 17 | jobs: 18 | sync-labels: 19 | uses: exercism/github-actions/.github/workflows/labels.yml@main 20 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | ## Introduction 4 | 5 | Exercism is a platform centered around empathetic conversation. We have a low tolerance for communication that makes anyone feel unwelcome, unsupported, insulted or discriminated against. 6 | 7 | ## Seen or experienced something uncomfortable? 8 | 9 | If you see or experience abuse, harassment, discrimination, or feel unsafe or upset, please email [abuse@exercism.org](mailto:abuse@exercism.org?subject=%5BCoC%5D) and include \[CoC\] in the subject line. We will follow up with you as a priority. 10 | 11 | ## Enforcement 12 | 13 | We actively monitor for Code of Conduct (CoC) violations and take any reports of violations extremely seriously. We have banned contributors, mentors and users due to violations. 14 | 15 | After we receive a report of a CoC violation, we view that person's conversation history on Exercism and related communication channels and attempt to understand whether someone has deliberately broken the CoC, or accidentally crossed a line. We generally reach out to the person who has been reported to discuss any concerns we have and warn them that repeated violations will result in a ban. Sometimes we decide that no violation has occurred and that no action is required and sometimes we will also ban people on a first offense. We strive to be fair, but will err on the side of protecting the culture of our community. 16 | 17 | Exercism's leadership reserve the right to take whatever action they feel appropriate with regards to CoC violations. 18 | 19 | ## The simple version 20 | 21 | - Be empathetic 22 | - Be welcoming 23 | - Be kind 24 | - Be honest 25 | - Be supportive 26 | - Be polite 27 | 28 | ## The details 29 | 30 | Exercism should be a safe place for everybody regardless of 31 | 32 | - Gender, gender identity or gender expression 33 | - Sexual orientation 34 | - Disability 35 | - Physical appearance (including but not limited to body size) 36 | - Race 37 | - Age 38 | - Religion 39 | - Anything else you can think of. 40 | 41 | As someone who is part of this community, you agree that: 42 | 43 | - We are collectively and individually committed to safety and inclusivity. 44 | - We have zero tolerance for abuse, harassment, or discrimination. 45 | - We respect people’s boundaries and identities. 46 | - We refrain from using language that can be considered offensive or oppressive (systemically or otherwise), eg. sexist, racist, homophobic, transphobic, ableist, classist, etc. - this includes (but is not limited to) various slurs. 47 | - We avoid using offensive topics as a form of humor. 48 | 49 | We actively work towards: 50 | 51 | - Being a safe community 52 | - Cultivating a network of support & encouragement for each other 53 | - Encouraging responsible and varied forms of expression 54 | 55 | We condemn: 56 | 57 | - Stalking, doxxing, or publishing private information 58 | - Violence, threats of violence or violent language 59 | - Anything that compromises people’s safety 60 | - Conduct or speech which might be considered sexist, racist, homophobic, transphobic, ableist or otherwise discriminatory or offensive in nature. 61 | - The use of unwelcome, suggestive, derogatory or inappropriate nicknames or terms. 62 | - Disrespect towards others (jokes, innuendo, dismissive attitudes) and towards differences of opinion. 63 | - Intimidation or harassment (online or in-person). Please read the [Citizen Code of Conduct](https://github.com/stumpsyn/policies/blob/master/citizen_code_of_conduct.md) for how we interpret harassment. 64 | - Inappropriate attention or contact. 65 | - Not understanding the differences between constructive criticism and disparagement. 66 | 67 | These things are NOT OK. 68 | 69 | Be aware of how your actions affect others. If it makes someone uncomfortable, stop. 70 | 71 | If you say something that is found offensive, and you are called out on it, try to: 72 | 73 | - Listen without interruption. 74 | - Believe what the person is saying & do not attempt to disqualify what they have to say. 75 | - Ask for tips / help with avoiding making the offense in the future. 76 | - Apologize and ask forgiveness. 77 | 78 | ## History 79 | 80 | This policy was initially adopted from the Front-end London Slack community and has been modified since. A version history can be seen on [GitHub](https://github.com/exercism/website-copy/edit/main/pages/code_of_conduct.md). 81 | 82 | _This policy is a "living" document, and subject to refinement and expansion in the future. This policy applies to the Exercism website, the Exercism GitHub organization, any other Exercism-related communication channels (e.g. Slack, Twitter, email) and any other Exercism entity or event._ 83 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Attribution 4.0 International Public License 2 | 3 | By exercising the Licensed Rights (defined below), You accept and agree 4 | to be bound by the terms and conditions of this Creative Commons 5 | Attribution 4.0 International Public License ("Public License"). To the 6 | extent this Public License may be interpreted as a contract, You are 7 | granted the Licensed Rights in consideration of Your acceptance of 8 | these terms and conditions, and the Licensor grants You such rights in 9 | consideration of benefits the Licensor receives from making the 10 | Licensed Material available under these terms and conditions. 11 | 12 | 13 | Section 1 -- Definitions. 14 | 15 | a. Adapted Material means material subject to Copyright and Similar 16 | Rights that is derived from or based upon the Licensed Material 17 | and in which the Licensed Material is translated, altered, 18 | arranged, transformed, or otherwise modified in a manner requiring 19 | permission under the Copyright and Similar Rights held by the 20 | Licensor. For purposes of this Public License, where the Licensed 21 | Material is a musical work, performance, or sound recording, 22 | Adapted Material is always produced where the Licensed Material is 23 | synched in timed relation with a moving image. 24 | 25 | b. Adapter's License means the license You apply to Your Copyright 26 | and Similar Rights in Your contributions to Adapted Material in 27 | accordance with the terms and conditions of this Public License. 28 | 29 | c. Copyright and Similar Rights means copyright and/or similar rights 30 | closely related to copyright including, without limitation, 31 | performance, broadcast, sound recording, and Sui Generis Database 32 | Rights, without regard to how the rights are labeled or 33 | categorized. For purposes of this Public License, the rights 34 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 35 | Rights. 36 | 37 | d. Effective Technological Measures means those measures that, in the 38 | absence of proper authority, may not be circumvented under laws 39 | fulfilling obligations under Article 11 of the WIPO Copyright 40 | Treaty adopted on December 20, 1996, and/or similar international 41 | agreements. 42 | 43 | e. Exceptions and Limitations means fair use, fair dealing, and/or 44 | any other exception or limitation to Copyright and Similar Rights 45 | that applies to Your use of the Licensed Material. 46 | 47 | f. Licensed Material means the artistic or literary work, database, 48 | or other material to which the Licensor applied this Public 49 | License. 50 | 51 | g. Licensed Rights means the rights granted to You subject to the 52 | terms and conditions of this Public License, which are limited to 53 | all Copyright and Similar Rights that apply to Your use of the 54 | Licensed Material and that the Licensor has authority to license. 55 | 56 | h. Licensor means the individual(s) or entity(ies) granting rights 57 | under this Public License. 58 | 59 | i. Share means to provide material to the public by any means or 60 | process that requires permission under the Licensed Rights, such 61 | as reproduction, public display, public performance, distribution, 62 | dissemination, communication, or importation, and to make material 63 | available to the public including in ways that members of the 64 | public may access the material from a place and at a time 65 | individually chosen by them. 66 | 67 | j. Sui Generis Database Rights means rights other than copyright 68 | resulting from Directive 96/9/EC of the European Parliament and of 69 | the Council of 11 March 1996 on the legal protection of databases, 70 | as amended and/or succeeded, as well as other essentially 71 | equivalent rights anywhere in the world. 72 | 73 | k. You means the individual or entity exercising the Licensed Rights 74 | under this Public License. Your has a corresponding meaning. 75 | 76 | 77 | Section 2 -- Scope. 78 | 79 | a. License grant. 80 | 81 | 1. Subject to the terms and conditions of this Public License, 82 | the Licensor hereby grants You a worldwide, royalty-free, 83 | non-sublicensable, non-exclusive, irrevocable license to 84 | exercise the Licensed Rights in the Licensed Material to: 85 | 86 | a. reproduce and Share the Licensed Material, in whole or 87 | in part; and 88 | 89 | b. produce, reproduce, and Share Adapted Material. 90 | 91 | 2. Exceptions and Limitations. For the avoidance of doubt, where 92 | Exceptions and Limitations apply to Your use, this Public 93 | License does not apply, and You do not need to comply with 94 | its terms and conditions. 95 | 96 | 3. Term. The term of this Public License is specified in Section 97 | 6(a). 98 | 99 | 4. Media and formats; technical modifications allowed. The 100 | Licensor authorizes You to exercise the Licensed Rights in 101 | all media and formats whether now known or hereafter created, 102 | and to make technical modifications necessary to do so. The 103 | Licensor waives and/or agrees not to assert any right or 104 | authority to forbid You from making technical modifications 105 | necessary to exercise the Licensed Rights, including 106 | technical modifications necessary to circumvent Effective 107 | Technological Measures. For purposes of this Public License, 108 | simply making modifications authorized by this Section 2(a) 109 | (4) never produces Adapted Material. 110 | 111 | 5. Downstream recipients. 112 | 113 | a. Offer from the Licensor -- Licensed Material. Every 114 | recipient of the Licensed Material automatically 115 | receives an offer from the Licensor to exercise the 116 | Licensed Rights under the terms and conditions of this 117 | Public License. 118 | 119 | b. No downstream restrictions. You may not offer or impose 120 | any additional or different terms or conditions on, or 121 | apply any Effective Technological Measures to, the 122 | Licensed Material if doing so restricts exercise of the 123 | Licensed Rights by any recipient of the Licensed 124 | Material. 125 | 126 | 6. No endorsement. Nothing in this Public License constitutes or 127 | may be construed as permission to assert or imply that You 128 | are, or that Your use of the Licensed Material is, connected 129 | with, or sponsored, endorsed, or granted official status by, 130 | the Licensor or others designated to receive attribution as 131 | provided in Section 3(a)(1)(A)(i). 132 | 133 | b. Other rights. 134 | 135 | 1. Moral rights, such as the right of integrity, are not 136 | licensed under this Public License, nor are publicity, 137 | privacy, and/or other similar personality rights; however, to 138 | the extent possible, the Licensor waives and/or agrees not to 139 | assert any such rights held by the Licensor to the limited 140 | extent necessary to allow You to exercise the Licensed 141 | Rights, but not otherwise. 142 | 143 | 2. Patent and trademark rights are not licensed under this 144 | Public License. 145 | 146 | 3. To the extent possible, the Licensor waives any right to 147 | collect royalties from You for the exercise of the Licensed 148 | Rights, whether directly or through a collecting society 149 | under any voluntary or waivable statutory or compulsory 150 | licensing scheme. In all other cases the Licensor expressly 151 | reserves any right to collect such royalties. 152 | 153 | 154 | Section 3 -- License Conditions. 155 | 156 | Your exercise of the Licensed Rights is expressly made subject to the 157 | following conditions. 158 | 159 | a. Attribution. 160 | 161 | 1. If You Share the Licensed Material (including in modified 162 | form), You must: 163 | 164 | a. retain the following if it is supplied by the Licensor 165 | with the Licensed Material: 166 | 167 | i. identification of the creator(s) of the Licensed 168 | Material and any others designated to receive 169 | attribution, in any reasonable manner requested by 170 | the Licensor (including by pseudonym if 171 | designated); 172 | 173 | ii. a copyright notice; 174 | 175 | iii. a notice that refers to this Public License; 176 | 177 | iv. a notice that refers to the disclaimer of 178 | warranties; 179 | 180 | v. a URI or hyperlink to the Licensed Material to the 181 | extent reasonably practicable; 182 | 183 | b. indicate if You modified the Licensed Material and 184 | retain an indication of any previous modifications; and 185 | 186 | c. indicate the Licensed Material is licensed under this 187 | Public License, and include the text of, or the URI or 188 | hyperlink to, this Public License. 189 | 190 | 2. You may satisfy the conditions in Section 3(a)(1) in any 191 | reasonable manner based on the medium, means, and context in 192 | which You Share the Licensed Material. For example, it may be 193 | reasonable to satisfy the conditions by providing a URI or 194 | hyperlink to a resource that includes the required 195 | information. 196 | 197 | 3. If requested by the Licensor, You must remove any of the 198 | information required by Section 3(a)(1)(A) to the extent 199 | reasonably practicable. 200 | 201 | 4. If You Share Adapted Material You produce, the Adapter's 202 | License You apply must not prevent recipients of the Adapted 203 | Material from complying with this Public License. 204 | 205 | 206 | Section 4 -- Sui Generis Database Rights. 207 | 208 | Where the Licensed Rights include Sui Generis Database Rights that 209 | apply to Your use of the Licensed Material: 210 | 211 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 212 | to extract, reuse, reproduce, and Share all or a substantial 213 | portion of the contents of the database; 214 | 215 | b. if You include all or a substantial portion of the database 216 | contents in a database in which You have Sui Generis Database 217 | Rights, then the database in which You have Sui Generis Database 218 | Rights (but not its individual contents) is Adapted Material; and 219 | 220 | c. You must comply with the conditions in Section 3(a) if You Share 221 | all or a substantial portion of the contents of the database. 222 | 223 | For the avoidance of doubt, this Section 4 supplements and does not 224 | replace Your obligations under this Public License where the Licensed 225 | Rights include other Copyright and Similar Rights. 226 | 227 | 228 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 229 | 230 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 231 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 232 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 233 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 234 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 235 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 236 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 237 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 238 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 239 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 240 | 241 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 242 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 243 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 244 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 245 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 246 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 247 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 248 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 249 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 250 | 251 | c. The disclaimer of warranties and limitation of liability provided 252 | above shall be interpreted in a manner that, to the extent 253 | possible, most closely approximates an absolute disclaimer and 254 | waiver of all liability. 255 | 256 | 257 | Section 6 -- Term and Termination. 258 | 259 | a. This Public License applies for the term of the Copyright and 260 | Similar Rights licensed here. However, if You fail to comply with 261 | this Public License, then Your rights under this Public License 262 | terminate automatically. 263 | 264 | b. Where Your right to use the Licensed Material has terminated under 265 | Section 6(a), it reinstates: 266 | 267 | 1. automatically as of the date the violation is cured, provided 268 | it is cured within 30 days of Your discovery of the 269 | violation; or 270 | 271 | 2. upon express reinstatement by the Licensor. 272 | 273 | For the avoidance of doubt, this Section 6(b) does not affect any 274 | right the Licensor may have to seek remedies for Your violations 275 | of this Public License. 276 | 277 | c. For the avoidance of doubt, the Licensor may also offer the 278 | Licensed Material under separate terms or conditions or stop 279 | distributing the Licensed Material at any time; however, doing so 280 | will not terminate this Public License. 281 | 282 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 283 | License. 284 | 285 | 286 | Section 7 -- Other Terms and Conditions. 287 | 288 | a. The Licensor shall not be bound by any additional or different 289 | terms or conditions communicated by You unless expressly agreed. 290 | 291 | b. Any arrangements, understandings, or agreements regarding the 292 | Licensed Material not stated herein are separate from and 293 | independent of the terms and conditions of this Public License. 294 | 295 | 296 | Section 8 -- Interpretation. 297 | 298 | a. For the avoidance of doubt, this Public License does not, and 299 | shall not be interpreted to, reduce, limit, restrict, or impose 300 | conditions on any use of the Licensed Material that could lawfully 301 | be made without permission under this Public License. 302 | 303 | b. To the extent possible, if any provision of this Public License is 304 | deemed unenforceable, it shall be automatically reformed to the 305 | minimum extent necessary to make it enforceable. If the provision 306 | cannot be reformed, it shall be severed from this Public License 307 | without affecting the enforceability of the remaining terms and 308 | conditions. 309 | 310 | c. No term or condition of this Public License will be waived and no 311 | failure to comply consented to unless expressly agreed to by the 312 | Licensor. 313 | 314 | d. Nothing in this Public License constitutes or may be interpreted 315 | as a limitation upon, or waiver of, any privileges and immunities 316 | that apply to the Licensor or You, including from the legal 317 | processes of any jurisdiction or authority. 318 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | This documentation is outdated. 2 | 3 | Up-to-date documentation is reflected on the Exercism site at https://exercism.org/docs. 4 | The repository for those docs can be found in https://github.com/exercism/docs 5 | -------------------------------------------------------------------------------- /about/README.md: -------------------------------------------------------------------------------- 1 | # Overview of Exercism 2 | 3 | Exercism—as an open source project—has two distinct parts. 4 | 5 | 1. The Product 6 | 2. The Curriculum 7 | 8 | Most open source projects are code that people incorporate into their own projects. They're tools and components used to build software: libraries and frameworks, packages and infrastructure. 9 | 10 | Exercism is unusual in the open source landscape. Exercism isn't a component or infrastructure. Exercism is an experience targeted at the end-user. 11 | 12 | If you want to follow the high-level goings-on of the Exercism project, watch the [discussions][] repository, and sign up for the [newsletter][]. 13 | 14 | You can also check out our high-level [roadmap][]. 15 | 16 | ## The Product 17 | 18 | The product consists of a website and a command-line client (CLI). 19 | 20 | We are currently investing our efforts in design research and product design towards a complete redesign and re-implementation of the website. As such, we would recommend that you do not invest time and effort in submitting changes to the website at this time. 21 | 22 | You can read more about our decision to do a full redesign in the article [The Delightful Design of Exercism][design-of-exercism], and the results of our first six months of work in the [resulting design documents][ux-insights]. 23 | 24 | You can get an overview of how the current product is put together in the [architecture][] document. 25 | 26 | ## The Curriculum 27 | 28 | The curriculum is much more like a traditional open source project than the product is. It consists of many small, well-defined components. If you wish to contribute to Exercism, we highly recommend contributing to the individual language tracks that make up the curriculum, or to the common pool of problem specifications. 29 | 30 | You can read more about [what our aim is for a language track][goals-exercism]. 31 | 32 | ### The Problem Specifications 33 | 34 | A problem specification is a description of a problem to solve. This description is not specific to any particular programming language or library or tool. 35 | 36 | An example is: 37 | 38 | > Determine whether or not a word is an [isogram][]. 39 | 40 | You could do this on the back of a napkin, or on a whiteboard, or by writing code. 41 | 42 | There are many ways to contribute to the problem specifications. 43 | 44 | - fix typos 45 | - improve exercise descriptions 46 | - document edge cases 47 | - discuss philosophical questions 48 | - make up more exercises 49 | - define canonical data-sets to make it easier to implement the exercise 50 | 51 | Th common pool of problem specifications is maintained in the [exercism/problem-specifications][problem-specifications] repository. You can check out the [open issues][problem-specifications-issues]. 52 | 53 | ### The Language Tracks 54 | 55 | Each language track implements exercises. These may be based on a problem specification from the common pool, or it may be a custom exercise defined specifically for that programming language. 56 | 57 | Each exercise consists of an mininum a README describing the problem to solve, and a collection of automated tests define the requirements of the solution. A good test suite will not mandate a particular approach, but will allow people to try many different approaches, and solve the exercise in many different ways. 58 | 59 | There are many ways to [contribute to a language track][getting-started-track]. You can find the repositories for the current language tracks in the list of repositories tagged with [exercism-track][]. 60 | 61 | [exercism-io]: https://github.com/exercism/exercism.io 62 | [cli]: https://github.com/exercism/cli 63 | [isogram]: https://en.wikipedia.org/wiki/Isogram 64 | [discussions]: https://github.com/exercism/discussions/issues 65 | [newsletter]: http://tinyletter.com/exercism 66 | [design-of-exercism]: http://tinyletter.com/exercism/letters/the-delightful-design-of-exercism 67 | [problem-specifications]: https://github.com/exercism/problem-specifications 68 | [problem-specifications-issues]: https://github.com/exercism/problem-specifications/issues 69 | [getting-started-track]: /contributing-to-language-tracks/README.md 70 | [ux-insights]: /about/conception/README.md 71 | [architecture]: /about/architecture.md 72 | [exercism-track]: https://github.com/search?q=org%3Aexercism+topic%3Aexercism-track 73 | [roadmap]: /about/roadmap.md 74 | [goals-exercism]: /about/goal-of-exercism.md 75 | -------------------------------------------------------------------------------- /about/architecture.md: -------------------------------------------------------------------------------- 1 | # Architecture of Exercism 2 | 3 | The main components that make up Exercism are: 4 | 5 | - [the website](#the-website) 6 | - [the CLI](#the-cli) 7 | - [the API](#the-api) 8 | - [Trackler](#trackler) 9 | 10 | ### The Website 11 | 12 | The [exercism.io](http://exercism.io/) website is a vital part of the [product](https://github.com/exercism/docs/blob/master/about/README.md#the-product). The community uses the site to: 13 | 14 | - get an overview of the available problems and languages 15 | - provide and receive feedback 16 | - learn by reading code 17 | - find links to useful learning resources 18 | 19 | ### The CLI 20 | 21 | The Command Line Interface (CLI) provides a way to fetch exercises and submit solutions to the site. It is a stand alone library so you don't need any particular language environment in order to use it. 22 | 23 | You can read more about the CLI in the corresponding GitHub [repository](https://github.com/exercism/cli). 24 | 25 | ### The API 26 | 27 | The API that services the command-line client lives in the [Exercism website repository](https://github.com/exercism/website). 28 | 29 | ### Trackler 30 | 31 | The [Trackler](https://github.com/exercism/trackler) is a Ruby gem that bundles the data for the exercises of all language tracks, providing a unified interface to the entire curriculum. 32 | -------------------------------------------------------------------------------- /about/conception/README.md: -------------------------------------------------------------------------------- 1 | # Conception 2 | 3 | We are exploring the deeper questions upon which Exercism is built: how do people learn, what drives motivation, and how do we best support people as they work towards their goals. 4 | 5 | At the moment we have delved into the questions at a philosophical level. 6 | 7 | **Please note that we are choosing to _not_ tackle the practical implications of these philosophical decisions at this time.** 8 | 9 | Once we feel that we have gotten the fundamental, driving questions right, we will explore how this will play out in terms of user flows, features, wireframes, and visual design. 10 | 11 | ## Motivation 12 | 13 | One of the core principles of Exercism is that people should do the exercises because they _want to_. Participation is voluntary, which means that we need to do our best to enhance motivation and break down barriers to success and fulfillment. 14 | 15 | The book [How Learning Works][how-learning-works] explores three different axes along which people's motivation is strengthened or weakened. 16 | 17 | * [**Perceived Value**](#perceived-value), explored in more depth in 18 | * [The Goals of Exercism][product-goals] 19 | * [Goals, Hopes and Dreams][user-goals] 20 | * [**Expectancies of Success**](#expectancies-of-success), explored in more depth in 21 | * [Progression][progression] 22 | * [**Environment**](#environment), explored in more depth in 23 | * [Emotional Journey][emotional-stages] 24 | * [Code Review][code-review] 25 | 26 | ## Perceived Value 27 | 28 | Perceived value can be linked to either the activity itself, or to outcomes. It might be intrinsic or extrinsic. It might be related to the learning, the challenge, social aspects of participating in the process, or something completely different. Value is deeply personal. 29 | 30 | We think that there are some broad themes in why people use Exercism. We've thought about what we believe Exercism can and should offer, how this aligns with people's goals, and the emotions that successful participation elicits. 31 | 32 | In the early days of Exercism, we did not have a clear concept of what problem Exercism was solving, and what value it delivered. As a result we did a poor job of communicating why you might use Exercism, and to what purpose. We have improved our own understanding dramatically since then, but have been less than successful in communicating this to potential participants. 33 | 34 | We have documented our thinking about [our goals][product-goals] and [their goals][user-goals], as communicating this clearly will be key to enhancing the motivation of those whose goals Exercism supports. 35 | 36 | ## Expectancies of Success 37 | 38 | People are more likely to be motivated if they believe they can succeed. Believing that they can succeed stems from: 39 | 40 | * having a clear plan of action 41 | * believing that following the plan will lead to the desired outcome 42 | * believing that they, personally, are capable of pursuing the plan to completion 43 | 44 | Historically Exercism's language tracks have had a clear plan of action: _do each exercise in succession until you're done_. It doesn't naturally follow, however, that following this plan will make you successful, nor are tracks structured to help ensure that people are able to follow through. 45 | 46 | As we explored the questions around success and motivation, it became clear that each exercise must feel like a step forward on a journey. Completion and progression are key. 47 | 48 | We are proposing [a new model for progression][progression] which we believe is much more likely to provide positive expectations of success. 49 | 50 | ## Environment 51 | 52 | In a hostile environment people need to continuously come up with reasons not to quit. In a supportive environment people are much more likely to be successful. 53 | 54 | We believe that there are three key times in a user's journey where we need to mitigate negative emotions in order to provide an environment that is supportive. 55 | 56 | * investing (time and effort) in a new online product 57 | * learning to code 58 | * receiving feedback 59 | 60 | We've written in depth about the user's [emotional journey][emotional-stages] through these three stages of using Exercism. 61 | 62 | Feedback and code review is one area where Exercism provides unique value. Historically, however, it is also where we have struggled the most. 63 | 64 | In [exercism/discussions#123][gamification], [@nilbus][] evaluates code review on Exercism against the elements of gameful design: 65 | 66 | > The code review system, viewed through a skill atom lens, is poorly designed for amplifying intrinsic value. The goals that the system communicates are weakly linked with learners' most likely motivations. Therefore, there is little motivation to overcome the challenges involved with providing good feedback and asking good questions. There are no expressed rules or guidelines to help focus reviews. Review feedback appears to be uncommon, and there are no suggestions for how to gain the most benefit from the code review process. There are plenty of intrinsic benefits in code review that could be amplified by Exercism, but these are not communicated effectively such that users will learn about or be reminded of them. 67 | 68 | Therefore, we have invested great effort into considering how to make [code review][code-review] on Exercism supportive and integral to people's success. 69 | 70 | [how-learning-works]: https://www.amazon.com/How-Learning-Works-Research-Based-Principles/dp/0470484101/ 71 | [product-goals]: /about/goal-of-exercism.md 72 | [user-goals]: /about/conception/goals.md 73 | [progression]: /about/conception/progression.md 74 | [emotional-stages]: /about/conception/emotional-stages/README.md 75 | [code-review]: /about/conception/code-review.md 76 | [gamification]: https://github.com/exercism/discussions/issues/123 77 | [@nilbus]: https://github.com/nilbus 78 | -------------------------------------------------------------------------------- /about/conception/code-review.md: -------------------------------------------------------------------------------- 1 | # Code Review 2 | 3 | We have found that people's opinions on code review and feedback are largely determined by the quality of the feedback, specifically with regard to the level of respect and pragmatism by the person providing feedback. 4 | 5 | In our explorations, fear and irritation both ranked as equally negative emotions that must be mitigated. 6 | 7 | As such, one of the key requirements for Exercism's success is how to ensure that feedback is: 8 | - Timely 9 | - Friendly 10 | - Respectful 11 | - Pragmatic 12 | - Provided with an adequate knowledge of the language 13 | - Provided with an understanding of the exercise 14 | 15 | Exercism is traditionally built around community-based moderation where anyone can feedback on another's exercise. One of our key areas of discussion has been to establish if that is a model that will provide feedback that meets with the goals listed about, or if the giving of feedback should be limited to a subset of users who are trained in this skill. In this document we describe these users as "mentors". 16 | 17 | In having this discussion we listed the pros of mentor-only feedback and community-feedback. 18 | 19 | ### Pros of mentor-only feedback 20 | 21 | We've grouped the benefits into different categories. 22 | 23 | #### Quality 24 | - The quality of the feedback will be consistently much higher 25 | - The quality of tone will be consistently much higher 26 | - We can give feedback on the feedback and the mentor will expect/appreciate that 27 | - We can ensure that people giving feedback know the things we want them to know about feedback 28 | - We can stop bad behaviors, patterns, and feedback as part of a process, not something that feels vindictive or elitist 29 | - Mentors will be invested in understanding the exercises better 30 | - Mentors will be invested in improving feedback 31 | - Feedback from different people will be more consistent 32 | - The person who receives feedback can be more confident that the feedback is worth acting on 33 | - The person who receives the feedback will likely prefer to get feedback from a "mentor", not a "rando" 34 | 35 | #### Processes 36 | - Our internal systems for feedback can be hackier/experimental, as we're working with a trusted group of people who can input on that. 37 | - Mentors will be able to compare notes and synthesize learnings. 38 | - There is a clearer separation of mentoring as a skill, and language-knowledge as a skill, and we can train the two things separately. 39 | - It's quicker to ramp up to mentoring in a new language track, because you already have the mentoring skills, even if you don't have the language skills right off the bat. 40 | 41 | #### Normal Site Usage 42 | - A user doesn’t feel pressure to start giving feedback right away 43 | - A user doesn’t feel a responsibility to mentor in a new language 44 | - At the end of a track users may feel like they've achieved something more tangible 45 | 46 | #### Aspiration 47 | - If mentoring on Exercism is respected and exciting people will be motivated to get the privilege 48 | - At the end of a track, there is a "next step" to become a mentor, which means it doesn't end with the last exercise 49 | - Mentors explicitly get skills that are transferrable to other contexts and platforms 50 | 51 | #### Marketing (Benefits to Exercism?) 52 | - Mentors might be involved in other projects (e.g. bootcamps) where they can use (and promote) Exercism to a wider audience 53 | - We can showcase mentors on a track to make it feel more exciting and valuable 54 | - It will feel like a much richer learning experience (you can get feedback from anyone on any website on the internet) 55 | - We are more likely to get top people giving feedback 56 | - Users will trust the product and process more and will therefore likely give more to it 57 | - It plays into the 1% rule (1% super users, 9% users, 90% rarely use it) 58 | 59 | ### Pros of Community Feedback 60 | - Everyone learns through teaching 61 | - We might get very surprising insights from people who haven't been "polluted" by our ideas about feedback 62 | - Variety of feedback might improve quality of feedback 63 | - More people giving feedback might mean that more people get feedback 64 | - We send the message implicitly that Exercism is about giving as well as taking 65 | - There's no barrier to someone getting involved 66 | - It's not elitist 67 | - More people might build friendships as a result of Exercism 68 | - Easier to explain (?) 69 | - Simpler in terms of implementation (?) 70 | 71 | In practice, our experience with community moderation is that the quality of feedback varies greatly and the negatives outweigh the positives. Much of the feedback is likely to be perceived as hostile, combative, or in other ways unsupportive. Additionally, lack of feedback is experienced as a negative (lack of support) rather than a neutral, especially because the product/experience depends on getting feedback. 72 | 73 | ### Conclusions 74 | 75 | Based on the above points, we believe that the right choice for Exercism is to restrict the giving of feedback to mentors. However, we feel that it is essential that the benefits of community feedback are not lost. Specifically we believe it is crucial to provide an onramp so that anyone who wants to can train to become a mentor. Mentorship must not be elitist and must not be restricted to the "superstars" of communities. Throughout the site, the option to become a mentor must be clear and welcoming. 76 | 77 | We considered the possible ways to "train" a mentor, and concluded that a mentorship track is the most Exercism-y way to do it. We propose creating a track that gives users moderation exercises where other mentors can then help them improve their moderating skills. This ensures that when a mentor graduates from that track, they will have come across a variety of different personalities and code issues, and be prepared to give feedback on a wide variety of exercises in an equally wide variety of situations. 78 | 79 | Such a mentorship track will need to address both code skills and interaction skills. Interaction skills can be taught by anyone who has them (in any language), whereas the code skills would need to be imparted by people who are mentors in that specific language. 80 | 81 | Having excellent moderation tools are of the utmost importance. We must have the ability to protect people from feeling attacked and harassed. 82 | -------------------------------------------------------------------------------- /about/conception/emotional-stages/README.md: -------------------------------------------------------------------------------- 1 | # The Involvement of Emotion in the User Experience 2 | 3 | _by [@nicolechalmers](https://github.com/nicolechalmers)_ 4 | 5 | **Removing Barriers to Usage** 6 | 7 | The aim of this document is to consider the feelings a user might experience over the duration of their relationship with Exercism - from the first touch point to the point where a user feels well embedded into the community and committed to the product. People experience varying levels of discomfort when trying something new and when learning new things. Identifying where our users will be most uncomfortable at this stage in the product design process is an important opportunity for us to remove/reduce any barriers that stop users progressing with Exercism and create an experience that is enjoyable. I’ve drawn out the user journey here: [User Journey](/about/conception/emotional-stages/user-journey.pdf). 8 | 9 | I’ve identified 3 main stages in the user journey where users are likely to have some negative feelings. 10 | 11 | * Investing in a new online product 12 | * Learning to code 13 | * Receiving feedback 14 | 15 | In lots of cases positive feelings (excitement, determination, past enjoyment) will override these negative feelings and users will carry on using the product normally, but in some cases they will result in users deciding not to sign up or dropping out. I’ve given thoughts on how we can reduce these occurrences. 16 | 17 | ## Investing in a new online product 18 | 19 | ![](/about/conception/emotional-stages/feelings-trying-something-new.png) 20 | 21 | The stages users move through to sign up to Exercism are: 22 | 23 | ### 1. Discovery 24 | 25 | There are different ways someone might first hear about Exercism i.e. via a Facebook advert or through a face-to-face conversation with a friend. At this stage our potential users will be intrigued and inspired to find out more. There won’t be any instinctive negative feelings around Exercism at this stage - perhaps a little skepticism. 26 | 27 | What we can do: 28 | 29 | - The most positive first touch point with Exercism will be via a recommendation / word of mouth. We can make sure any recommend a friend incentives, social shares from Exercism etc. are really appealing and informative. 30 | - We can have a clear and memorable tagline so recommenders can instantly explain Exercism in a super-clear way. 31 | - Have good open-graph cards so where-ever Exercism appears in social media it has clear brand explanation. 32 | 33 | ### 2. Research 34 | 35 | Those who have heard about Exercism through word of mouth or via a blog/magazine will feel more instinctively trustful of the product and are likely to do less/no research before signing up. 36 | Others will want to read more about the product - they might visit the Exercism landing page and/or google “Exercism” to see what others are saying about it and how it compares to alternative sites. 37 | 38 | **Negative Emotions to mitigate:** skeptical, distrustful, overwhelmed 39 | 40 | What we can do: 41 | 42 | - Make sure landing page copy encourages trust. With Meducation we found testimonials worked well, affiliation with trusted brands e.g. “Exercism, as featured in Wired” “Sponsored by GitHub”, highlighting any awards won, mention size of community “over X members”, feature any tech influencers who are involved 43 | - Make it clear why we are different from competitor products and who we cater for. 44 | - In all our copy and communication I think we should keep the tone really down to earth, not salesy and make the company/community feel really transparent - I think this is the way to gain trust. This is what has worked really well so far so we should continue with the same tone of voice. 45 | - Emphasis on the fact Exercism is free - nothing to lose and we’re not going to try and get anything from you in the future (e.g. money, commitment) 46 | 47 | ### 3. Decision to Sign Up 48 | 49 | The next step is where the user chooses whether or not to sign up - do they click the button or do they not? Choices are stressful for us because we’re fearful of making the wrong decision or that our choices will mean change. 50 | 51 | **Negative Emotions to mitigate:** fear, wariness, hesitant 52 | 53 | What we can do: 54 | 55 | - We need to make the landing page, blog posts etc. sound and feel exciting, like an opportunity not to be missed - this should overpower any doubts people have about signing up. 56 | - Encourage desire to learn through Exercism through blog posts. Write posts around the method of learning, the thought (and science) that’s gone into designing the tracks and the product. If we can excite potential users in this way before they even hit the landing page, they will be less hesitant to sign up as they will be more informed about the product and what they can expect to gain from it. 57 | - Be clear and transparent about next steps and how long they will take - “we’ll ask you a few details”, “you’ll choose a language track”, “you can start learning” etc. 58 | - Clear and detailed FAQs so people know what they’re getting themselves into - “can I remain anonymous”, “how long does a track take” etc. If people still have questions make it easy for them to contact us. 59 | - Consistent and clear call to actions on each page. 60 | 61 | ### 4. Parting with Personal Details 62 | 63 | The user has decided to give it a go but will be very wary of giving away personal details, email address, GitHub profile etc. This is a key place to enforce trust and enforce the user’s decision to sign up. 64 | 65 | Although Exercism is free, we shouldn’t underestimate what it takes for someone to hand over their email address. Email addresses are like a new currency, people need to understand what they’re getting in return for their investment, just like they are parting with money. 66 | 67 | **Negative Emotions to mitigate:** fear, worry, reluctance, fight or flight 68 | 69 | What we can do: 70 | 71 | - We shouldn’t ask too much at once, we can ask skills based questions later so as not to overwhelm the user at this point 72 | - Have a side bar of Common Questions e.g. Can I be anonymous? 73 | - Reiterate the benefits of Exercism 74 | - Show more testimonials to reinforce user’s decision and encourage them to continue 75 | 76 | ### 5. Final Commitment 77 | 78 | At this point the user has invested quite a lot into the website so probably won’t still be in decision making mode. This is a good time to positively reinforce their decision to sign up and get the user excited about what’s to come. 79 | 80 | **Negative Emotions to mitigate:** regret, confusion 81 | 82 | What we can do: 83 | 84 | - Make this last step really easy and manage expectations about what’s coming next. 85 | - Nice welcoming design will help user feel like they made a good decision and they’re in a safe space. 86 | - Emphasis that they’ve joined X other people and that this decision will pay dividends for years to come. 87 | 88 | ## Learning to code 89 | 90 | People need to experience a certain level of discomfort in order to learn. Everyone will have a different tolerance to discomfort and a different level of necessary discomfort to learn. For Exercism, we need to decide how much discomfort we want users to feel at different points e.g. do tracks include a combination of deep, hard exercises and easy exercises that go over what user has already learnt (to give them a boost) or do we make it clear that the exercises are hard so those who sign up need to have the patience and determination to push through. Much of this is about expectation management. I’m sure Katrina will have lots of thoughts on this and would’ve applied lots of her knowledge to the tracks already, so it would be great to understand all of that to make sure we’re aligned to existing learnings. 91 | 92 | Reading: [Why Learning to Code is So Damn Hard][so-damn-hard] 93 | [so-damn-hard]: https://www.vikingcodeschool.com/posts/why-learning-to-code-is-so-damn-hard 94 | 95 | ![](/about/conception/emotional-stages/feelings-learning-to-code.png) 96 | 97 | **Negative Emotions to mitigate:** frustration, disappointment, confusion, isolation 98 | 99 | What we can do: 100 | 101 | - Have encouraging and motivating copy surrounding exercise content. 102 | - To manage expectations, make it clear when users are about to come across something difficult e.g. “You’ll probably find X difficult because we haven’t covered Y yet. This is totally fine just do your best and we’ll fill in the gaps later” - the book I’m using to learn Python is very much like this and it makes me feel really calm and comforted. 103 | - Get users to choose how difficult they found each exercise at the end and why (like Freeletics App). We could use this data later on to determine which exercise users might do next or provide recommended reading. 104 | - Highlight idioms and concepts in the exercise description so users can easily refresh their memories on things they’ve forgotten. This will rely on us having a bank of explanations, forum threads or links to other sites. 105 | - Constantly showing personal progression and success to encourage people that they have already achieved things. 106 | - Reminding people what they’ll achieve if they continue the whole track, and the level of expertise they can achieve. Think about “How you could use this in the real world?” 107 | - Exciting facts around the site (Did you know that the last mission to Mars used this thing in Java). Make you realise that the small things are powerful, e.g. a loop feels stupidly basic, but a well optimised loop can make the difference between success and failure in a spacestation context. 108 | 109 | ## Receiving feedback (e.g. code reviews) 110 | 111 | ![](/about/conception/emotional-stages/feelings-code-review.png) 112 | 113 | Our survey and Twitter poll have informed us that overall people welcome code reviews but much prefer those that have been delivered well. When code reviews are delivered badly they can generate lots of negative emotions and could turn users away from the product. 114 | 115 | Reading: [How Positive and Negative Feedback Motivate Goal Pursuit][feedback-goal-pursuit] 116 | [feedback-goal-pursuit]: https://faculty.chicagobooth.edu/ayelet.fishbach/research/FEF%20Compass%202010.pdf 117 | 118 | **Negative Emotions to mitigate:** uncomfortable, irritated, frustrated, deflated, demotivated, defensive, condescended, conflict-adverse. 119 | 120 | What we can do: 121 | 122 | - Treat every piece of feedback as an opportunity to make users love Exercism a bit more. Not many online products get the opportunity to interact with their users in this way - we shouldn't underestimate the value of it. 123 | - Create lots of blog and video content highlighting how to give great code reviews. 124 | - Create blog posts and share research around how best to receive feedback e.g. http://coachingleaders.co.uk/the-emotionally-intelligent-way-to-receive-feedback/. 125 | - Provide training (via a track) on how to give good feedback. Show examples of bad feedback and explain why they’re bad. Make sure the guidance on giving feedback is aligned with our core values and the culture we want to develop e.g. do we want feedback to be quite light hearted and jokey or do we want to focus on simplicity even if this means the feedback has less personality? 126 | - Give users the ability to flag up bad feedback. 127 | - Choose mentors with credibility/experience. 128 | - Ask people how they found the feedback after they complete an exercise. Encourage them to actively engage in the process. 129 | -------------------------------------------------------------------------------- /about/conception/emotional-stages/feelings-code-review.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/exercism/legacy-docs/514b200470058838f74775b51203ccfefc614f10/about/conception/emotional-stages/feelings-code-review.png -------------------------------------------------------------------------------- /about/conception/emotional-stages/feelings-learning-to-code.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/exercism/legacy-docs/514b200470058838f74775b51203ccfefc614f10/about/conception/emotional-stages/feelings-learning-to-code.png -------------------------------------------------------------------------------- /about/conception/emotional-stages/feelings-trying-something-new.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/exercism/legacy-docs/514b200470058838f74775b51203ccfefc614f10/about/conception/emotional-stages/feelings-trying-something-new.png -------------------------------------------------------------------------------- /about/conception/emotional-stages/user-journey.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/exercism/legacy-docs/514b200470058838f74775b51203ccfefc614f10/about/conception/emotional-stages/user-journey.pdf -------------------------------------------------------------------------------- /about/conception/goals.md: -------------------------------------------------------------------------------- 1 | # Goals, Hopes, and Dreams 2 | 3 | People might use Exercism for any number of reasons. Some reasons are things people have shared explicitly, other reasons we've devined from interacting with Exercism users over the course of several years. 4 | 5 | We've grouped the goals into two categories—those that we think fit with Exercism, and those that we consider out of scope for the product. We assign no judgement to people's goals. We do not think the goals in the latter category are less valid than the goals in the former, only that Exercism cannot fulfill all needs for all people. 6 | 7 | Understanding [what Exercism is and what it is not][goals-of-exercism] will enable us to make it the best product possible. 8 | 9 | For people who come to Exercism looking for the out of scope goals we will endeavour to point them to other websites, projects, or resources that might better suit their needs. 10 | 11 | #### In scope 12 | - Learn a language 13 | - Get better at a language 14 | - Gain fluency in a language 15 | - Be able to join a language community 16 | - Get feedback on their programming style in a language 17 | - Enjoy programming in a language (fun / therapy / escapism) 18 | 19 | #### Out of scope 20 | - Get a job in X 21 | - Learn how to do X in a language 22 | - Learn common libraries in a language 23 | - Write a project (that is not possible in their current languages) but is typically done in X 24 | - Contribute to an OSS project in X 25 | - Gain the ability to teach others 26 | 27 | While using Exercism might help people achieve these goals, we are not going to design the product to explicitly support these outcomes. 28 | 29 | ## Emotional Success 30 | 31 | It is important that people feel like they're developing throughout the process of using Exercism, and that at the end of a track there should be a sense of completion and satisfaction/empowerment. 32 | 33 | We believe the key emotions are: 34 | 35 | - **Confident**: the confidence to do something with their new skill, be it teach, learn more, contribute, or showcase their new skill by adding the language to their bio. They should feel like they could do a lightning talk at a meetup about something they learned. They should be able to pair with someone in a language. While Exercism doesn't necessarily give you the skills to teach or contribute to open source, completing a track in Exercism should make you feel confident that you can do those things. 36 | - **Comfortable/Empowered**: able to tackle all the resources that exist on the internet for diving into the depths of a language. 37 | - **Satisfied/Proud**: a sense of accomplishment at having completed something. 38 | - **Excited**: having completed a language track on Exercism people are poised at the door of many new opportunities. 39 | 40 | It's also possible and perfectly reasonable to assume that people might feel nothing in particular, other than that they're done, and that they're moving on (pragmatism). 41 | 42 | Supporting a sense of complection, satisfaction and empowerment ties into our exploration of [expectancies of success][expectancies]. 43 | 44 | [goals-of-exercism]: /about/goals-of-exercism.md 45 | [expectancies]: /about/conception/README.md#expectancies-of-success 46 | -------------------------------------------------------------------------------- /about/conception/progression.md: -------------------------------------------------------------------------------- 1 | # Progression in Learning & Exercism 2 | 3 | A feeling of progression is key in nearly all human endeavour, but especially when investing in education. You must feel that there is some end in sight and that you are moving towards it. In education, this can be hard, especially in subjects in which practice is a core tenet. Think back to school when you were doing math homework and had to wade through hundreds of examples in algebra. While many of us probably took some perverse delight in this, for most students this sort of practice is painful and disheartening because it is hard to gauge progress. Variety is in short supply and boredom easily sets in. 4 | 5 | Within the realm of Exercism this means that: 6 | 1. A student should be progressing towards an end-goal of gaining fluency and confidence in a language. 7 | 1. That progress should be visible and understandable with a goal in sight. 8 | 1. It should be clear to the student what they have learned so far. 9 | 10 | Currently Exercism does not strongly adhere to these principles. The exercises are structured in a strict linear manner, and there is no meaningful end in sight. As we add more exercises, the goal post appears to move. Many exercises are variations on themes, making the progression seems somewhat arbitrary. It's not obvious what any of the exercises are about, and as people work their way through a track, it's not clear what someone may have learned. 11 | 12 | Ideally, we'd structure the progression in a way that more easily accommodates people's individual needs. We want to allow people to dive deep into a topic if they wish to, or practice concepts that they find more difficult to assimilate, or simply play with language features that they find particularly appealing, skipping past those exercises which do not interest them. 13 | 14 | ## Learnings from Role Playing Games (RPGs) 15 | 16 | RPGs are games where you are a character acting out a role in an explorable world. Modern games focus on freedom, allowing you to explore huge worlds that would take hours to walk across. As you explore these worlds you come across other characters who set you off on "quests". For example, in Skyrim, you might bump into a peasant asking you to rescue his son who has been taken by a vampire. In Assassin's Creed you might meet Michelangelo who needs help delivering a new invention or painting to a local ruler. These games give you a vast amount of functionality - you can fight, seek out plants from the wilderness and craft potions, use complex magic systems, negotiate, solve puzzles, and a huge amount more. 17 | 18 | Whether you have prior experience with the genre or not, starting out in a world that is alien to you is entirely overwhelming. There is a huge array of controls, options, paths, and interactions. At the beginning you can probably work out how to walk around, but that's about it. In modern large RPGs, learning the full array of the functionality takes dozens of hours. 19 | 20 | Turning this complexity into fun is where good games shine. The main mechanism for achieving this is by providing a *main storyline* - normally a series of 10-30 core quests that each teach you the next thing you need to know to progress. For example, the first quest is often talking to someone, with a tutorial as you go along that teaches you the basics of walking, talking, etc. The next quest might then be to help that person fight a baddie, teaching you about the combat system. As you go through each quest, you won't necessarily realise you are learning new skills as you are focused on the engaging storyline, but the core function is progression. The main storyline of a game normally takes 20-40 hrs to complete, and usually accounts for 3-10% of the total game. 21 | 22 | The rest of the game is made up of *side quests*. These are tasks, split into categories, ever-increasing in difficulty, that allow you to practice a new skill. Side quests are unlocked when you complete a quest in the main storyline. For example, as soon as you complete the first quest of talking to someone, you will then *unlock* a load of similar quests. These would appear in the game as people you can go and talk to who have a basic tasks (find my child who has run off, take a message to my sister, etc). These side quests can often be taken in any order. Once you complete the first core fighting quest, you might then run into someone who asks you to rescue their brother from a baddie, which involves fighting, etc. Side quests often have some indication of difficulty before you start them. In some games this is represented by money: "if you do this I'll give you $10" vs "if you do this I'll give you $1,000" - in other games it might be a more explicit pause in the game that gives you information about the task before you start. 23 | 24 | The people playing the games don't know that they're practicing a skill in a side-quest. As far as they're concerned, they are just playing a cool new mission where they get to run across roofs really quickly, or they get to race against a thief. In the same way a baby doesn't know that the purpose of it trying to fit square blocks into multi-shaped holes is so that it can improve its motor-skills or develop depth perception, a gamer doesn't necessarily understand that the point of side quests is to improve. And of course, there is a degree of pure enjoyment and fun, just as the baby experiences. 25 | 26 | Linked to the first point, but also distinctive - people don't associate unlocked quests with completing a certain mission. There's no timeline that says "because you completed core:6 you now get side:40-53. Suddenly there's just more available to them. That links well with the "variable reward" concept that's used in building habit-forming products, where you don't know what's going to happen when you complete something, leading to excitement and a (totally artificial) feeling of serendipity. This is a good thing from a UX POV. 27 | 28 | Typically you've completed an RPG when you've completed all of the core quests. The main storyline generally gets harder with each quest. As soon as you've completed a core quest you have the option of attempting the next core quest directly. The jump in skill is significant, however, so most players find that they need to sharpen their skills in side quests before continuing the main storyline. Thus, completing an RPG often takes an order of magnitude longer than it would to complete only the main storyline. 29 | 30 | 31 | ## Meaningful and Flexible Linear Progression in Exercism 32 | 33 | While we have no intention of making Exercism look anything like a video game, the concept of a meaningful linear progression consisting of core exercises, each of which unlocks exercises that are variations on the core theme is useful. It seems to fit well with what it's like to learn a programming language. When learning a new programming language there are probably a dozen or so core topics that you need to cover, but achieving fluency means lots of practice and lots of edge cases. In a language track on Exercism, we might have six exercises all about editing text. To some people these feel like the same thing, to others they feel vastly different. In reality, both things are true - they all have to do with manipulating text and therefore cover the same core topic, but they touch on different techniques, idioms, and edge-cases. It would therefore be logical to have a core text exercise that gives an overview of manipulating text to the user. Once they've completed it they can say "I understand the basics of strings in this programming language". Having completed this exercise, five optional exercises would be unlocked which could be solved in any order, and which would deal with a variety of subtleties of strings in that language. 34 | 35 | The core exercises give learners a clear path forward; the end is in sight. 36 | 37 | For a student learning a completely new programming language, completing the 10-20 core exercises would give students confidence that they've touched on the full range of key concepts. They could complete just the main exercises and confidently start experimenting with real-world technologies. Or they could complete all the related "side quests", and develop a greater fluency and ease in the basics of the language. Equally a student who is diving more deeply into a language they know can quickly skip past more fundamental topics and spend more time delving into a set of exercises that push their understanding of a more esoteric topic. This gives us a balance between rapid progression and depth. 38 | 39 | This also means we can have infinite exercises per track. As long as the core stays lean and each side exercise can logically be unlocked by completing a core exercise, then everything will feel structured and rich. 40 | 41 | Moving towards a model with a mainline with optional explorations will mean that we will need to consider our exercise metadata much more carefully than we have until now. If we are willing to have 100(s) of exercises on a track, it needs to be clear to a learner what the core concepts of each exercise is about, how difficult it is, how long it might take, etc. This will allow Exercism to be broad and deep without being overwhelming. 42 | -------------------------------------------------------------------------------- /about/glossary.md: -------------------------------------------------------------------------------- 1 | # Glossary 2 | 3 | There are a number of terms that we use that have specific meaning within the 4 | context of Exercism. 5 | 6 | ## Summary 7 | 8 | People come to Exercism for the exercises and each **exercise** consists of the **specification** of a problem to solve and a concrete **implementation** of that problem. 9 | 10 | The **solution** to an exercise is made up of one or more **iterations** 11 | 12 | | Term | Explanation | 13 | |--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| 14 | | **exercise** | an instance of a problem, made up of a **specification** and its **implementation** | 15 | | **implementation** | a **language** specific test suite and documentation used to implement a **specification** | 16 | | **iteration** | the code that someone writes to make a test suite pass | 17 | | **language** | the name of a programming language, for example _C++_ or _Haskell_ | 18 | | **problem** | the abstract concept of a programming task on exercism.io | 19 | | **slug** | a short, unique identifier for a **problem**, **specification**, or **exercise** (e.g. `hamming`). Consists of lowercase words separated by hyphens | 20 | | **solution** | a collection of **iterations** that a single person has done to solve an **exercise** | 21 | | **specification** | a language-agnostic description of a **problem**. These live in the [problem-specifications](https://github.com/exercism/problem-specifications) repository | 22 | | **track** | a collection of **exercises** implemented in a given **language** | 23 | | **track id** | a short, unique identifier for a track (e.g. `cpp` or `haskell`). Consists of lowercase words separated by hyphens | 24 | -------------------------------------------------------------------------------- /about/goal-of-exercism.md: -------------------------------------------------------------------------------- 1 | # The Goal of Exercism 2 | 3 | The goal of a language track on Exercism is to give people a way to achieve a high level of fluency at a low level of proficiency. 4 | 5 | We're aiming for fluency in the syntax, idioms, and the standard library of the language. 6 | 7 | The [Language Hunters][language-hunters] describe fluency as 8 | 9 | > What you can say when you're woken up in the middle of the night with a flashlight in your face. 10 | 11 | This is distinct from the concept of _proficiency_, which is not about ease, but about degree. 12 | 13 | They describe four levels of proficiency: 14 | 15 | 1. **Simple, concrete ideas** - this is often enough to awkwardly get through simple day-to-day transactions. "Thirsty". "Good music". "One more". 16 | 1. **Simple, complete sentences** - the ability to make simple conversation, and understand the responses. 17 | 1. **Complex sentences** - you can have interesting conversations, tell stories. 18 | 1. **Complex ideas** - you can discuss complicated things like social, economic, and political topics. 19 | 20 | You can have the ability to perform at a level without being able to do so under stress. Proficiency does not automatically mean fluency. 21 | 22 | While these were defined in the context of human languages, they map quite well to programming languages. 23 | 24 | 1. **Basic syntax** - the ability to use basic data structures and features of the language 25 | 1. **Simple programs** - you can string a small program together to solve a small problem 26 | 1. **Real-world programs** - you can use the programming language to solve day-to-day problems using the tools and libraries in the broader ecosystem of the language. 27 | 1. **Deep knowledge of the language and ecosystem** - rather than using what is there, you now contribute to inventing new tools, improving the language, and evolving the ecosystem 28 | 29 | Within this framework, with Exercism we're aiming for a high degree of fluency at a level 2 proficiency. This bridges the gap between "Hello, World" and productivity. 30 | 31 | Being fluent at this basic level lets people put all of their focus on thinking at a higher, more useful level. It also puts them in a good position to consume the existing resources and documentation for the language. 32 | 33 | [language-hunters]: http://languagehunters.org/ 34 | -------------------------------------------------------------------------------- /about/roadmap.md: -------------------------------------------------------------------------------- 1 | # Roadmap 2 | 3 | [design-of-exercism]: http://tinyletter.com/exercism/letters/the-delightful-design-of-exercism 4 | 5 | We have two separate roadmaps, one for the overall product, and one for the curriculum, which encompasses all of the exercises for all of the supported programming languages. 6 | 7 | ## The Product 8 | 9 | We are currently investing efforts in a complete reboot of the Exercism website. The original site was never designed, it just kind of happened, organically over time. We are now going back to basics, working with design professionals to ask the fundamental questions that will inform the user experience. 10 | 11 | The core idea of Exercism is a good one, and there are some things that work extremely well. Most of the user experience, however, is not as delightful as it could be. 12 | 13 | Once we have explored the key questions, we will progress to exploring wireframes and user flows, and then eventually visual design and writing copy. At the very end of this, we will implement the new website completely from scratch, focusing on clean, simple, idiomatic code, and good performance. 14 | 15 | We will release the new website under the same license as the existing one. 16 | 17 | For updates, sign up for the "behind the scenes" [newsletter][]. 18 | 19 | ## The Curriculum 20 | 21 | For the curriculum, the focus is on _sustainability_. We need to have enough people maintaining and contributing to each language track that no single person gets overwhelmed or burned out. In order to achieve this, we will be working to make it easier to get started contributing to a language track, as well as figuring out how to reach and entice more potential contributors. 22 | 23 | At the level of each individual track, we're working on improving the experience for people working through the solutions. Each exercise should be compelling, it should inspire useful, interesting conversations, and the difficulty of exercises throughout the track should gradually increase. 24 | 25 | [newsletter]: http://tinyletter.com/exercism 26 | -------------------------------------------------------------------------------- /about/scope-of-a-track.md: -------------------------------------------------------------------------------- 1 | # The scope of a track 2 | 3 | Exercism's sweet spot is to bridge that awkward gap between an effortful "hello world" and being able to fluently express simple ideas idiomatically using the basic features of a language along with its standard library. 4 | 5 | There are a few key ideas here: 6 | 7 | * **basics:** basic syntax, basic language features, commonly used standard library packages or modules 8 | * **fluency:** ease and familiarity, not having to think about syntax 9 | * **idioms:** using the conventions that are common for the language 10 | 11 | Familiarity with third party libraries is notably absent from this list. 12 | As is the ability to write scalable, production-worthy code and solve real-world problems. 13 | 14 | There are plenty of resources available that cover more advanced topics, but it's challenging to make use of them without fluency in the basics. 15 | 16 | ## What makes a good track? 17 | 18 | A good track targets a programming language. 19 | It provides lots of small exercises, each of which is self-contained. 20 | 21 | It covers all the language features that are used in the normal day-to-day work of a programmer writing code in that language. 22 | It provides opportunities to discover and make use of the most commonly used packages or modules in the standard library. 23 | 24 | ## What is out of scope? 25 | 26 | There are many interesting topics and exercises that _could_ be added to Exercism, but that probably shouldn't. 27 | 28 | ### Specialty libraries and techniques 29 | 30 | In [exercism/exercism.io#3113](https://github.com/exercism/exercism.io/issues/3113) [Jim Rybarski](https://github.com/jimrybarski) brought up the idea of adding exercises that teach introductory image analysis with Python and `scikit-image`. 31 | 32 | Image analysis is a great topic, and the `scikit-image` library is a useful library, but it is not targeting fluency in basic Python, and is therefore a great example of something which is out of scope for Exercism. 33 | 34 | ### Not programming languages 35 | 36 | Early on someone requested that we add a track for math proofs. 37 | 38 | A project that provides lots of little exercises helping people get better at math proofs would be really cool—it just doesn't fit within the framework of Exercism. 39 | 40 | ### Not _really_ programming languages 41 | 42 | In [exercism/discussions#84](https://github.com/exercism/discussions/issues/84) Brian Hicks wondered whether or not we should have a track for JSON after observing that people do some funny things with it. 43 | 44 | JSON is markup, not a programming language. 45 | People absolutely do funny things with it—and it's a worthy topic for teaching best practices, but it's not a great fit for an Exercism track. 46 | 47 | The same goes for HTML and CSS, which have also been requested. 48 | 49 | ### Big, real-world-sized problems 50 | 51 | While it would be undeniably useful to practice navigating in large codebases and refactoring extremely complex code, adding these sorts of exercises would stretch the format of Exercism beyond the breaking point. 52 | 53 | ## What does this mean for existing tracks? 54 | 55 | An Exercism track can be improved by considering several different questions: 56 | 57 | * Are there language features that are not (or are only sparsely) covered by exercises? 58 | * Are there parts of the standard library that are unlikely to be used in solutions to existing exercises? 59 | 60 | Additionally, it's worth considering that we're targeting fluency. 61 | We're not just trying to introduce a topic, we want people to have ample opportunity to practice and play around with it. 62 | A good track will often provide numerous exercises that all touch on similar areas. 63 | -------------------------------------------------------------------------------- /contributing-to-language-tracks/README.md: -------------------------------------------------------------------------------- 1 | # Getting Involved in an Exercism Language Track 2 | 3 | [repositories]: http://exercism.io/repositories 4 | [triaging-issues]: /you-can-help/triage-issues.md 5 | [reviewing-prs]: /you-can-help/review-pull-requests.md 6 | [porting]: /you-can-help/implement-an-exercise-from-specification.md 7 | [problem-specifications]: https://github.com/exercism/problem-specifications 8 | [blazon]: https://github.com/exercism/blazon 9 | [blazon-process]: /you-can-help/improve-exercise-metadata.md 10 | [fixing-readmes]: /language-tracks/exercises/anatomy/readmes.md 11 | 12 | The Exercism language tracks are a great way to get involved in: 13 | 14 | - A programming language you love. 15 | - A programming language you're curious about. 16 | - Open source (in general). 17 | 18 | _If you haven't used Exercism before, then it could be worth submitting solutions to a couple of exercises._ 19 | _It doesn't matter which language track you submit to, it's just to get a feel for what a language track consists of._ 20 | 21 | ## About the language tracks 22 | 23 | Each language track lives in its own repository, which means that you can contribute 24 | to a track without having to know anything about the rest of the Exercism ecosystem. 25 | 26 | Also, each track is focused, containing implementations of trivial exercises and the tools 27 | to make development easier, so there's no big codebase to get acquainted with. 28 | 29 | You can see a list of all the available tracks by looking at the [exercism-track topic on the Exercism org](https://github.com/search?q=topic%3Aexercism-track+org%3Aexercism&type=Repositories) on GitHub. 30 | 31 | Some tracks are active on the website (see https://exercism.io/#explore-languages if logged out, or http://exercism.io/tracks regardless of whether you're logged in). Tracks that are not active on the site are either in progress, or someone was optimistic but it never got any traction and they didn't get it to the point where it could launch. 32 | 33 | ## Ways to contribute 34 | 35 | There are a number of ways to contribute to a track. All of them are sorely needed, and greatly appreciated! 36 | 37 | First, orient yourself. 38 | Read the README, and look through the open issues and pull requests, and get a feel for what's going on. 39 | 40 | You can pick up an open issue, or help with: 41 | 42 | * Improving product-facing copy/documentation 43 | * Improving contributor-facing documentation and tooling 44 | * Improving existing exercises 45 | * Adding more exercises 46 | * Triaging issues 47 | * Review pull requests 48 | 49 | ### Improve product-facing copy/documentation 50 | 51 | The main introduction page for a track can be seen on the website by going to https://exercism.io/tracks/$TRACK_ID. 52 | 53 | For example, here's the [R track](https://exercism.io/tracks/r). 54 | 55 | There are three pieces of content that come from the track repository: 56 | 57 | - the blurb, which is right under that track name in the header. It lives in `config.json` as a top-level key "blurb". 58 | - the "about" section, which is in `docs/ABOUT.md` 59 | - the code example, which is in `docs/SNIPPET.txt` 60 | 61 | We also have guides that are linked to from each exercise page: 62 | 63 | - Installing the language (`docs/INSTALLATION.md`) 64 | - Running the tests (`docs/TESTS.md`) 65 | - Learning the language (`docs/LEARNING.md`) 66 | - Useful language resources (`docs/RESOURCES.md`) 67 | 68 | ### Improve contributor-facing documentation 69 | 70 | It's not always obvious how to get started contributing to a language track. 71 | As you get involved, help improve the README in the track repository. 72 | 73 | * Are there undocumented dependencies? 74 | * How do you run the tests? Is there a way to run all the tests for all the exercises? 75 | * Are there any naming conventions for files or types or classes or functions? 76 | * Is there any tooling that we're using? Linters? 77 | * Is there continuous integration? Are there any gotchas? 78 | 79 | ### Improve existing exercises 80 | 81 | #### Exercise READMEs 82 | 83 | If the README is ambiguous or confusing, then there's almost certainly 84 | something we can do to clarify. 85 | 86 | Or maybe you found a typo (you wouldn't be the first). 87 | 88 | The READMEs are generated, and all the details are explained [here][fixing-readmes]. 89 | 90 | #### Test Suites 91 | 92 | * Did the test suite force you towards a certain solution? (It shouldn't.) 93 | * Did you come across a solution that passed the tests, but that had a bug? 94 | (Maybe we're missing a test case.) 95 | 96 | The test suite is straight forward to find: look in the `exercises` 97 | directory in the language track repository for the directory named after the 98 | slug of the exercise. The test file will be right there. 99 | 100 | That said, some test suites are generated based on the `canonical-data.json` 101 | file found in [problem-specifications][]. The README for the language track repository 102 | should tell you what you need to know. 103 | 104 | For every change that you make to the test suite, ask yourself: **Should this 105 | change also affect other language tracks that implement the same exercise?** 106 | 107 | If you think it might, open a discussion in the [problem-specifications][] repository and get 108 | other track implementors' feedback on the subject. 109 | 110 | If this change should affect the broader Exercism curriculum, then use the 111 | issue in [problem-specifications][] to: 112 | 113 | - Hash out all the details together. 114 | - Figure out the necessary changes to the `canonical-data.json` for the 115 | exercise (if it exists). 116 | - Draft an issue that can be submitted to all the tracks that implement the 117 | exercise using the [blazon][] tool (which automates the tedious parts). 118 | More about that [here][blazon-process]. 119 | 120 | #### Exercise metadata 121 | 122 | Exercises have topics and a difficulty score in the `config.json` file in the track. 123 | These are used to help filter exercises on the site. 124 | 125 | #### Reordering Exercises 126 | 127 | We don't have a formal process for deciding how the exercises should be 128 | ordered. We also don't have any particular guidelines yet, about which 129 | optional exercises should be unlocked by which core exercises. 130 | 131 | The order of the core exercises is decided by the `exercises` array in `config.json`. 132 | 133 | ### Adding Hints 134 | 135 | Sometimes an exercise is in the right place in the sequence, but it's really 136 | hard to figure out how to solve it anyway. 137 | 138 | In this case consider whether there's a blog post or some documentation that 139 | you could point people to, and add it to `$ROOT/exercises/$SLUG/.meta/hints.md` in the exercise directory 140 | in the language track. If the file doesn't exist, create a new one. 141 | 142 | ### Add new exercises 143 | 144 | The easiest way to add a new exercise is to find an exercise that has already been implemented in another language 145 | track, and port it over to your target language. 146 | 147 | We've got [a guide][porting] that walks you through how to find an exercise to port, and the things to 148 | keep in mind when implementing it. 149 | 150 | ### Triage issues 151 | 152 | A great issue is detailed and actionable. 153 | When they're not, you can help ask the questions to make them so. 154 | For more detailed suggestions about things to keep in mind when triaging, check out [this documentation][triaging-issues]. 155 | 156 | ### Review pull requests 157 | 158 | We always need more eyeballs on pull requests. On language tracks most pull requests tend to be related to 159 | the exercises themselves, and we have [detailed documentation][reviewing-prs] that should help 160 | you get started with code reviews. 161 | 162 | ## Want to help keep an eye on things? 163 | 164 | We can always use an extra pair of eyes. 165 | Go to the repository for the language you've chosen, click the _Watch_ button, and select _Watching_. 166 | This will notify you of any new issues, pull requests, or comments in the repository, which is a great way 167 | of getting acquainted with the people involved and the issues that tend to come up. 168 | 169 | -------------------------------------------------------------------------------- /contributing/filing-a-bug-report.md: -------------------------------------------------------------------------------- 1 | # Writing an Actionable Bug Report 2 | 3 | We're a work in progress. You reporting bugs in a clear and actionable format is a big help. Thanks!! 4 | 5 | When writing a bug, please include: 6 | 7 | 1. the steps you took to get to the defect (number the steps using a little markdown, as shown below). 8 | 1. what you *expected* to happen after the last step. 9 | 1. what *actually* happened after the last step. 10 | 1. information about your particular situation: 11 | * if it's happening while you're using the CLI, include the **redacted** output of `exercism debug`. _Redacted_ means remove your API key from the output before including in the issue. 12 | * if it's happening on the website, include your OS and browser versions. 13 | 14 | ## Example 15 | 16 | I recently completed the Hello World for Java. 17 | 18 | * I submitted the file (I got the success message). 19 | * I went to the link provided by the CLI. 20 | * **Expected:** to see my submission, 21 | * **Actual:** I got a 404. 22 | 23 | Here's my "exercism debug": 24 | ``` 25 | **** Debug Information **** 26 | Exercism CLI Version: 2.3.0 27 | Exercism CLI Latest Release: 2.3.0 28 | OS/Architecture: darwin/amd64 29 | Build OS/Architecture / 30 | Home Dir: /Users/jtigger 31 | Config file: /Users/jtigger/.exercism.json 32 | API Key: ******* 33 | Exercises Directory: /Users/jtigger/workspace/exercism/exercises 34 | Testing API endpoints reachability 35 | * API: http://exercism.io [connected] 350.644953ms 36 | * GitHub API: https://api.github.com/ [connected] 386.82533ms 37 | * XAPI: http://x.exercism.io [connected] 796.511395ms 38 | ``` 39 | 40 | which formats to: 41 | 42 | I recently completed the Hello World for Java. 43 | 44 | * I submitted the file (I got the success message). 45 | * I went to the link provided by the CLI. 46 | * **Expected:** to see my submission, 47 | * **Actual:** I got a 404. 48 | 49 | Here's my "exercism debug": 50 | ``` 51 | **** Debug Information **** 52 | Exercism CLI Version: 2.3.0 53 | Exercism CLI Latest Release: 2.3.0 54 | OS/Architecture: darwin/amd64 55 | Build OS/Architecture / 56 | Home Dir: /Users/jtigger 57 | Config file: /Users/jtigger/.exercism.json 58 | API Key: ******* 59 | Exercises Directory: /Users/jtigger/workspace/exercism/exercises 60 | Testing API endpoints reachability 61 | * API: http://exercism.io [connected] 350.644953ms 62 | * GitHub API: https://api.github.com/ [connected] 386.82533ms 63 | * XAPI: http://x.exercism.io [connected] 796.511395ms 64 | ``` 65 | -------------------------------------------------------------------------------- /contributing/git-basics.md: -------------------------------------------------------------------------------- 1 | # Git Basics 2 | 3 | If you're concerned that you haven't done it right, don't worry. Submit your pull request, and we'll help you get the details sorted out. 4 | 5 | ## Getting the Code 6 | 7 | We recommend forking the project first, and then cloning the fork. 8 | 9 | ```bash 10 | git clone git@github.com:/.git 11 | ``` 12 | 13 | This will give you a remote repository named `origin` that points to your own copy of the project. 14 | 15 | In addition to this, we recommend that you add the original repository as a secondary remote. 16 | 17 | ```bash 18 | git remote add upstream https://github.com/exercism/.git 19 | ``` 20 | 21 | The names `origin` and `upstream` are pretty standard, so it's worth getting used to the names in your own work. 22 | 23 | ## Branches 24 | 25 | When working on your fork it tends to make things easier if you never touch the master branch. 26 | 27 | The basic workflow becomes: 28 | 29 | * check out the master branch 30 | * pull from `upstream` to make sure everything is up to date 31 | * push to `origin` so you have the latest code in your fork 32 | * check out a branch 33 | * make the changes, commit them 34 | * rebase onto the upstream master (and resolve any conflicts) 35 | * push your branch up to `origin` 36 | * submit a pull request 37 | 38 | If you're asked to tweak your work, you can keep pushing it to the branch, and it automatically updates the pull request with the new commits. 39 | 40 | ## Commit Messages 41 | 42 | Commit messages are communication and documentation. They're a log of more 43 | than just _what_ happened, they're about _why_ it was done. 44 | 45 | The longer a project is active, the more people involved, the larger the 46 | codebase, the more important it is to have good commit messages. 47 | 48 | There's an excellent lightning talk by Ryan Geary called [Do Your Commit 49 | Messages 50 | Suck?](https://www.youtube.com/watch?v=8YjSty6bfog). 51 | It's funny and enlightening, and you should watch it. 52 | 53 | Two articles that have very clear guidelines about how to write 54 | excellent commit messages are Tim Pope's 55 | [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 56 | and Chris Beams' [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/). 57 | Please read them. 58 | 59 | ### Examples 60 | 61 | Imagine that you're submitting a new problem called "spinning-wheel" to the Ruby track. 62 | 63 | Here's a fairly typical set of commits that you might end up making: 64 | 65 | ```bash 66 | 433a0e1 added spinning wheel tests 67 | 1f7d4aa pass spinning wheel 68 | cf21737 oops 69 | be4c410 rename example file 70 | bb89a77 update config 71 | ``` 72 | 73 | All of these commits are about a single thing: adding a new problem. They 74 | should be a single commit. They don't have to start out that way (life is 75 | messy), but once you're done, you should squash everything into one commit, 76 | and rename it cohesively: 77 | 78 | ```bash 79 | f4314e5 add spinning wheel problem 80 | ``` 81 | 82 | ## Resetting `master` 83 | 84 | If you've already made changes on your master so that it has diverged from the 85 | upstream you can reset it. 86 | 87 | First create a backup of your branch so that you can find any changes. Just in 88 | case. 89 | 90 | ```bash 91 | git checkout master 92 | git checkout -b backup 93 | git checkout master 94 | ``` 95 | 96 | Next, fetch the most recent changes from the upstream repository and reset master to it. 97 | 98 | ```bash 99 | git fetch upstream 100 | git reset --hard upstream/master 101 | ``` 102 | 103 | If you do a git log at this point you'll see that you have *exactly* the 104 | commits that are in the upstream repository. Your commits aren't gone, they're 105 | just not in master anymore. 106 | 107 | To put this on your GitHub fork, you'll probably need to use the `--force` flag: 108 | 109 | ```bash 110 | git push --force origin master 111 | ``` 112 | 113 | ## Squashing 114 | 115 | Squashing commits into a single commit is particularly useful when the change 116 | happened in lots of little (sometimes confusing) steps, but it really is one 117 | change. 118 | 119 | There are a number of ways to accomplish this, and many people like to use an 120 | [interactive rebase](#interactive-rebase), but it can be tricky if you haven't set git up to open 121 | your favorite editor. 122 | 123 | An easier way to do this is to un-commit everything, putting it back into the 124 | staging area, and then committing it again. 125 | 126 | Using the example from above, we have 5 commits that should be squashed into one. 127 | 128 | ```bash 129 | 433a0e1 added spinning wheel tests 130 | 1f7d4aa pass spinning wheel 131 | cf21737 oops 132 | be4c410 rename example file 133 | bb89a77 update config 134 | ``` 135 | 136 | To un-commit them, use the following incantation: 137 | 138 | ```bash 139 | $ git reset --soft HEAD^^^^^ 140 | ``` 141 | 142 | Notice that there are 5 carets, one for each commit that you want to 143 | un-commit. You could also say: 144 | 145 | ```bash 146 | $ git reset --soft HEAD~5 147 | ``` 148 | 149 | If you do a `git status` now, you'll see all the changed files, and they're 150 | staged and ready to commit. If you do a `git log`, you'll see that the most 151 | recent commit is from someone else. 152 | 153 | Next, commit, as usual: 154 | 155 | ```bash 156 | $ git commit -m "Add spinning wheel problem" 157 | ``` 158 | 159 | Now if you do a `git status` you may get a warning saying that your origin and 160 | your branch have diverged. This is completely normal, since the origin has 5 161 | commits and you have 1 (different) one. 162 | 163 | The next step is to force push this up to your branch, which will 164 | automatically update the pull request, replacing the old commits with the new 165 | one. 166 | 167 | ```bash 168 | $ git push --force origin spinning-wheel 169 | ``` 170 | 171 | ## Resources 172 | 173 | If you're completely new to git, there are a number of resources that can help 174 | get you feeling more comfortable with it. 175 | 176 | * [Git Immersion](http://gitimmersion.com/) 177 | * [GitHug](https://github.com/Gazler/githug) 178 | * [Try GitHub](http://try.github.io) 179 | 180 | If you've been using git for a while, but it feels like repeating magical 181 | incantations (while praying that nothing goes wrong), then you may find these 182 | helpful: 183 | 184 | * [Git for Ages 4 and Up](https://www.youtube.com/watch?v=1ffBJ4sVUb4) - video of a presentation/demo 185 | * [Think Like a Git](http://think-like-a-git.net/) 186 | * [Explain Git with D3](https://onlywei.github.io/explain-git-with-d3/) - interactive site 187 | * [Pro Git](http://git-scm.com/book/en/v2) - "The Book" for learning Git in detail 188 | * [Git Branching Tutorial](http://pcottle.github.io/learnGitBranching/) - interactive tutorial, very visual 189 | 190 | ## Rebasing 191 | 192 | You'll often be asked to rebase your branch before we merge a pull request as Exercism likes to keep a linear project commit history. This is accomplished with git rebase. It takes the current branch and places all the commits at the front of the branch that you're rebasing with. 193 | 194 | For example, rebasing the current branch on top of upstream/master: 195 | ``` 196 | git rebase upstream/master 197 | ``` 198 | Project commit history: 199 | ``` 200 | -- current branch -- 201 | / 202 | --- master branch ---- 203 | ``` 204 | 205 | ### Interactive Rebase 206 | The rebase command has an option called `-i, --interactive` which will open an editor with a list of the commits which are about to be changed. This list accepts commands, allowing the user to edit the list before initiating the rebase action. 207 | 208 | Using the example from above, we have 5 commits that should be squashed into one. 209 | 210 | ```bash 211 | 433a0e1 added spinning wheel tests 212 | 1f7d4aa pass spinning wheel 213 | cf21737 oops 214 | be4c410 rename example file 215 | bb89a77 update config 216 | ``` 217 | 218 | To interactively rebase, use the following incantation: 219 | 220 | ```bash 221 | $ git rebase -i HEAD~5 222 | ``` 223 | This will bring up an editor with the following information: 224 | 225 | ```bash 226 | pick 433a0e1 added spinning wheel tests 227 | pick 1f7d4aa pass spinning wheel 228 | pick cf21737 oops 229 | pick be4c410 rename example file 230 | pick bb89a77 update config 231 | 232 | # 233 | # Commands: 234 | # p, pick = use commit 235 | # r, reword = use commit, but edit the commit message 236 | # e, edit = use commit, but stop for amending 237 | # s, squash = use commit, but meld into previous commit 238 | # f, fixup = like "squash", but discard this commit's log message 239 | # x, exec = run command (the rest of the line) using shell 240 | # 241 | # These lines can be re-ordered; they are executed from top to bottom. 242 | # 243 | # If you remove a line here THAT COMMIT WILL BE LOST. 244 | # 245 | # However, if you remove everything, the rebase will be aborted. 246 | # 247 | # Note that empty commits are commented out 248 | ``` 249 | 250 | By choosing the `reword` command for the top commit and choosing the `fixup` command for the remaining commits, you will be able to squash the commits into one commit and provide a descriptive summary of the entire change 251 | 252 | ```bash 253 | reword 433a0e1 added spinning wheel tests 254 | fixup 1f7d4aa pass spinning wheel 255 | fixup cf21737 oops 256 | fixup be4c410 rename example file 257 | fixup bb89a77 update config 258 | ``` 259 | 260 | [Further Reading](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 261 | -------------------------------------------------------------------------------- /contributing/providing-feedback.md: -------------------------------------------------------------------------------- 1 | Please intend to help your fellow programmers improve. There is a [time](http://proco.stanford.edu/) and [place](https://www.codewars.com/) for competition, it's not here. 2 | 3 | ## Tips 4 | 5 | Here's a collection on easy-to-digest bits; pick one at random for inspiration in leaving constructive feedback on submissions: 6 | 7 | - Make your feedback more digestible: start by pointing out something you really liked about this submission. 8 | - Imagine this person is you when you first started in the language. 9 | - With each challenge, include a piece of support. 10 | - What if you framed your feedback as a question to encourage curiosity, rather than a correcting directive? 11 | - Consider leaving a praise-only comment on this one. 12 | - Imagine you're warmly welcoming someone to your country when introducing them to the idioms and ways-of-thinking of the language. 13 | - Empathize: is your feedback worded in a way that you could easily take? 14 | -------------------------------------------------------------------------------- /contributing/pull-request-guidelines.md: -------------------------------------------------------------------------------- 1 | # Pull Request Guidelines 2 | 3 | 1. Put the name of the exercise in the subject line of the commit. 4 | E.g. `hamming: Add test case for strands of unequal length` 5 | 1. The subject line should be a one-sentence summary, and should not include 6 | the word *and* (explicitly or implied). 7 | 1. Any extra detail should be provided in the body of the PR. 8 | 1. Don't submit unrelated changes in the same pull request. 9 | 1. If you had a bit of churn in the process of getting the change right, 10 | squash your commits. Refer to the guidelines on [squashing commits](/contributing/git-basics.md#squashing). 11 | 1. If you had to refactor in order to add your change, then we'd love to 12 | see two commits: First the refactoring, then the added behavior. It's 13 | fine to put this in the same pull request, unless the refactoring is 14 | huge and would make it hard to review both at the same time. 15 | 1. If you are referencing another issue or pull-request, for instance 16 | *closes #XXX* or *see #XXX*, please include the reference in the body of the PR, 17 | rather than the subject line. This is simply because the subject line doesn't 18 | support markdown, and so these don't get turned into clickable links. It makes 19 | it harder to follow and to go look at the related issue or PR. 20 | 1. Please also refer to the guidelines for [commit messages](/contributing/git-basics.md#commit-messages). 21 | 22 | Once you've submitted a pull request, one or more of the track maintainers 23 | will review it. Some tracks are less active and might not have someone 24 | checking in every day. If you don't get a response within a couple of days, 25 | feel free to ping us in the [support 26 | chat](https://gitter.im/exercism/support). 27 | -------------------------------------------------------------------------------- /finding-your-way.md: -------------------------------------------------------------------------------- 1 | # Finding Your Way 2 | 3 | [ref-problem]: #i-see-a-problem 4 | [ref-idea]: #i-have-an-idea 5 | [ref-help]: #i-would-like-to-help 6 | 7 | | [I see a problem][ref-problem] | [I have an idea][ref-idea] | [I would like to help][ref-help] | 8 | |:---:|:---:|:---:| 9 | |[I see a problem][ref-problem] | [I have an idea][ref-idea] | [I would like to help][ref-help] | 10 | 11 | ---- 12 | 13 | ## I see a problem 14 | 15 | [ref-problem-site]: #i-see-a-problem-on-the-website 16 | [ref-problem-cli]: #i-see-a-problem-with-the-command-line-client-cli 17 | [ref-problem-starting]: #i-see-a-problem-getting-started-with-a-language 18 | [ref-problem-exercise]: #i-see-a-problem-with-a-specific-exercise 19 | 20 | 21 | | [on the website][ref-problem-site] | [with the command-line client (CLI)][ref-problem-cli] | [getting started with a language][ref-problem-starting] | [with a specific exercise][ref-problem-exercise] | 22 | |:---:|:---:|:---:|:---:| 23 | | [I see a problem on the website][ref-problem-site] | [I see a problem with the CLI][ref-problem-cli] | [I see a problem getting started with a language][ref-problem-starting] | [I see a problem with a specific exercise][ref-problem-exercise] | 24 | 25 | ### I see a problem on the website 26 | 27 | - If you're having trouble figuring out how to do something on the website, jump in the [online support chat][chat] and ask there. 28 | - Check out [exercism/exercism.io][exercism-bugs]'s repo for bugs; and while we might know there's an issue, any additional details sometimes can help. 29 | - If the website has a bug, you can help by [filing a bug report][filing-bug] in the [exercism/exercism.io][exercism-new-issue] repository. 30 | - if you have the time and the desire, you can help *even more* by [fixing it][ref-help-web]. 31 | 32 | ### I see a problem with the command-line client (CLI) 33 | 34 | - If you're having trouble installing or working with the CLI, ask for help in our [online support chat][chat]. 35 | - It may be a reported/known bug; check [exercism/cli][cli-bugs]'s repo for bugs. 36 | - If the CLI has a bug, you can help by [filing a bug report][filing-bug] in the [exercism/cli repository][cli-new-issue]. 37 | - if you have the time and the desire, you can help *even more* by [fixing it][ref-help-go]. 38 | 39 | ### I see a problem getting started with a language 40 | 41 | - If you're having trouble with the setup instructions, ask for help in our [online support chat][chat]. 42 | - If you see a problem with the setup instructions, you can help by [filing a bug report][filing-bug] in the "Issues" section of the [corresponding language repository][track-repos]. 43 | - if you have the time and the desire, you can help *even more* by [fixing it][ref-help-track]. 44 | 45 | ### I see a problem with a specific exercise 46 | 47 | - If a particular exercise is giving you grief, ask for help in our [online support chat][chat]. 48 | - If there's a defect in the... 49 | - **instructions** of the exercise, you can make a difference by [filing a bug report][filing-bug] in the [exercism/problem-specifications][common-new-issue] repository. 50 | - if you have the time and the desire, you can help *even more* by [fixing it][ref-help-track]. 51 | - **tests** or **starter code** of the exercise, you can help by [filing a bug report][filing-bug] in the "Issues" section of the [corresponding language repository][track-repos]. 52 | - if you have the time and the desire, you can help *even more* by [fixing it][ref-help-track]. 53 | - You can ask for help within the track: 54 | - `exercism submit` the code you have; 55 | - Follow the link that the CLI returns to view your new submission on the website; 56 | - In the "**Manage**" pull-down (top-right), select "**Request Help**". 57 | When you do this, your submission is highlighted, letting others know you're stuck. 58 | 59 | ---- 60 | 61 | ## I have an idea 62 | 63 | [ref-idea-site]: #i-have-an-idea-about-making-the-website-better 64 | [ref-idea-cli]: #i-have-an-idea-about-improving-the-command-line-client-cli 65 | [ref-idea-curriculum]: #i-have-an-idea-about-a-brand-new-exercise-for-exercism 66 | [ref-idea-exercise]: #i-have-an-idea-about-improving-an-existing-exercise 67 | 68 | | [making the website better][ref-idea-site] | [improving the command-line client (CLI)][ref-idea-cli] | [a brand-new exercise for Exercism][ref-idea-curriculum] | [improving an existing exercise][ref-idea-exercise] | 69 | |:---:|:---:|:---:|:---:| 70 | |[I have an idea about making the website better][ref-idea-site] | [I have an idea about improving the command-line client][ref-idea-cli] | [I have an idea about a brand new exercise for Exercism][ref-idea-curriculum] | [I have an idea about improving an existing exercise][ref-idea-exercise] | 71 | 72 | ### I have an idea about making the website better 73 | 74 | We're currently working with professional user experience designers on rethinking the entire experience from scratch. Check out the [roadmap][] for more details about this. 75 | 76 | ### I have an idea about improving the command-line client (CLI) 77 | 78 | Current specific discussions: 79 | 80 | - Overall user experience with the CLI: [exercism/discussions#129][discussion-cli-ux]. 81 | 82 | Here are some helpful starter searches in the two repositories that contain ideas about the CLI: 83 | 84 | - [exercism/cli][cli-issues] 85 | - [exercism/discussions?cli][discussions-cli] 86 | 87 | If the idea isn't being discussed yet, kick it off in the [exercism/cli][cli-new-issue]. 88 | 89 | ### I have an idea about a brand-new exercise for Exercism 90 | 91 | New exercise ideas are definitely welcome! Here's how to ensure the idea lands in the right place: 92 | 93 | - Check to see if the exercise is listed: https://github.com/exercism/problem-specifications/tree/master/exercises. 94 | - If it is there, but not in the language you'd like to solve it in, put in a request in [that particular language's repository][track-repos]. 95 | - if you have the time and the desire, you can help *even more* by [implementing it][ref-help-track]. 96 | - If it is not there, suggest it in [exercism/problem-specifications][common-new-issue]. 97 | - if you have the time and the desire, you can help *even more* by [implementing it][how-to-new-exercise]. 98 | - If you know of a good source of potential new problems, please share: [exercism/problem-specifications#107][issue-exercise-ideas]. 99 | 100 | ### I have an idea about improving an existing exercise 101 | 102 | - If the idea is to improve the... 103 | - **instructions** of the exercise, you can make a difference by making the suggestion in the [exercism/problem-specifications repository][common-new-issue]. 104 | - if you have the time and the desire, you can help *even more* by [fixing it][how-to-exercise-readmes]. 105 | - **tests** or **starter code** of the exercise, you can help by making the suggestion in the "Issues" section of the [corresponding language repository][track-repos]. 106 | - if you have the time and the desire, you can help *even more* by [fixing it][ref-help-track]. 107 | 108 | ---- 109 | 110 | ## I would like to help 111 | 112 | [ref-help-docs]: #i-would-like-to-help-i-can--want-to-get-better-at-technical-writing-and-organization 113 | [ref-help-track]: #i-would-like-to-help-i-am-fluent-in--want-to-get-better-at-a-particular-programming-language 114 | [ref-help-web]: #i-would-like-to-help-i-know--want-to-get-better-at-web-programming 115 | [ref-help-ruby]: #i-would-like-to-help-i-know--want-to-get-better-at-ruby 116 | [ref-help-go]: #i-would-like-to-help-i-know--want-to-get-better-at-go 117 | [ref-help-design]: #i-would-like-to-help-i-know--want-to-get-better-at-web-design 118 | [ref-help-mentoring]: #i-would-like-to-help-i-know--want-to-get-better-at-mentoring-others 119 | [ref-help-organizing]: #i-would-like-to-help-i-can--want-to-get-better-at-organizing-stuff 120 | 121 | | [with technical writing and organization][ref-help-docs] | [with a particular programming language][ref-help-track] | [with web programming][ref-help-web] | [with development in Ruby][ref-help-ruby] | [with development in Go][ref-help-go] | [with web design][ref-help-design] | [by mentoring others][ref-help-mentoring] 122 | |:---:|:---:|:---:|:---:|:---:|:---:|:---:| 123 | | [I want to help with technical writing and organization][ref-help-docs] | [I want to help with a particular programming language][ref-help-track] | [I want to help with web programming][ref-help-web] | [I want to help with Ruby][ref-help-ruby] | [I want to help with Go][ref-help-go] | [I want to help with web design][ref-help-design] | [I want to help with mentoring others][ref-help-mentoring] 124 | 125 | ### I would like to help; I can / want to get better at technical writing and organization 126 | 127 | - Find discussions about ways we'd like to improve our documentation: [exercism/discussions?documentation][discussions-docs]. 128 | - Check out the [open issues][docs-issues] in the docs repository. 129 | - Help make the instructions of an exercise more clear, interesting and/or engaging by [tweaking its README.md][how-to-exercise-readmes]. 130 | - Issues across all of Exercism looking for help with documentation: [exercism?documentation][org-issues-docs]. 131 | 132 | ### I would like to help; I am fluent in / want to get better at a particular programming language 133 | 134 | Are you a language enthusiast? Help other people fall in love with your language by... 135 | 136 | #### Mentoring Others 137 | 138 | - Give feedback on other's submissions in your [activity stream][activity-stream]. 139 | - Help others get unstuck in the [support chat][chat]. 140 | - However you support others, aim to do it [the Exercism way][feedback]. 141 | 142 | #### Contributing to a Language Track 143 | 144 | This means helping maintain the code of the exercises and supporting tooling for a particular language. 145 | 146 | - [Find a language][track-repos] you love or want to get to know better. 147 | - Orient yourself through our [guide to getting involved in a track][contributing-tracks]. 148 | 149 | ### I would like to help; I know / want to get better at web programming 150 | 151 | At the moment we're not encouraging people to contribute to the website, since we're working on a completely new site. 152 | To hear about it when we're ready for input, feedback, thoughts, and opinions, watch the [discussions repository][discussions-repo]. 153 | 154 | ### I would like to help; I know / want to get better at Ruby 155 | 156 | At the moment we're not encouraging people to contribute to the website, since we're working on a completely new site. 157 | To hear about it when we're ready for input, feedback, thoughts, and opinions, watch the [discussions repository][discussions-repo]. 158 | 159 | ### I would like to help; I know / want to get better at Go 160 | 161 | One of the more subtle but important parts of the Exercism experience is our CLI; it's written in Go. 162 | 163 | - Setup your local development environment for the CLI: [exercism/cli][cli-repo]. 164 | - Locate a feature/bug to work on: [exercism/cli][cli-issues]. 165 | - Work the issue: [the contribution workflow][contribution-workflow]. 166 | 167 | ### I would like to help; I know / want to get better at web design 168 | 169 | At the moment we're not encouraging people to contribute to the website, since we're working on a completely new site. 170 | To hear about it when we're ready for input, feedback, thoughts, and opinions, watch the [discussions repository][discussions-repo]. 171 | 172 | ### I would like to help; I know / want to get better at mentoring others 173 | 174 | Do you like mentoring people? 175 | 176 | - Hang out in the support chat [support chat][chat], or 177 | - submit an exercise so you can [give feedback to people who have submitted it, too][activity-stream]. 178 | 179 | [chat]: https://gitter.im/exercism/support 180 | [filing-bug]: /contributing/filing-a-bug-report.md 181 | [feedback]: /contributing/providing-feedback.md 182 | [contributing-tracks]: /contributing-to-language-tracks/README.md 183 | [io-local-env]: https://github.com/exercism/exercism.io/blob/master/docs/setting-up-local-development.md 184 | [contribution-workflow]: https://github.com/exercism/exercism.io/issues/3252 185 | [overview-architecture]: /about/architecture.md 186 | [exercism-bugs]: https://github.com/exercism/exercism.io/issues?q=is%3Aissue+is%3Aopen+label%3Abug 187 | [exercism-new-issue]: https://github.com/exercism/exercism.io/issues/new 188 | [cli-bugs]: https://github.com/exercism/cli/issues?q=is%3Aissue+is%3Aopen+label%3Abug 189 | [cli-new-issue]: https://github.com/exercism/cli/issues/new 190 | [common-new-issue]: https://github.com/exercism/problem-specifications/issues/new 191 | [discussions-new-issue]: https://github.com/exercism/discussions/issues/new 192 | [roadmap]: /about/roadmap.md 193 | [discussion-cli-ux]: https://github.com/exercism/discussions/issues/129 194 | [cli-issues]: https://github.com/exercism/cli/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc 195 | [discussions-cli]: https://github.com/exercism/discussions/issues?q=is%3Aissue+is%3Aopen+cli+sort%3Aupdated-desc 196 | [how-to-new-exercise]: https://github.com/exercism/problem-specifications/blob/master/CONTRIBUTING.md#implementing-a-completely-new-exercise 197 | [issue-exercise-ideas]: https://github.com/exercism/problem-specifications/issues/107 198 | [how-to-exercise-readmes]: /language-tracks/exercises/anatomy/readmes.md 199 | [discussions-docs]: https://github.com/exercism/discussions/issues?q=is%3Aissue+is%3Aopen+documentation+sort%3Aupdated-desc 200 | [docs-issues]: https://github.com/exercism/docs/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc 201 | [org-issues-docs]: https://github.com/search?o=desc&p=1&q=org%3Aexercism+documentation+is%3Aissue&ref=searchresults&s=updated&state=open&type=Issues&utf8=%E2%9C%93 202 | [activity-stream]: http://exercism.io/inbox 203 | [exercism-good-first-patch]: https://github.com/exercism/exercism.io/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+patch%22 204 | [cli-repo]: https://github.com/exercism/cli 205 | [discussions-repo]: https://github.com/exercism/discussions 206 | [track-repos]: https://github.com/search?q=org%3Aexercism+topic%3Aexercism-track 207 | -------------------------------------------------------------------------------- /language-tracks/README.md: -------------------------------------------------------------------------------- 1 | # Language Tracks 2 | 3 | A language track on Exercism is meant to bridge the awkward gap between "hello world" and feeling productive. 4 | We're aiming for a high degree of fluency in the basic syntax, standard library, and idioms of the language. 5 | In other words, a [high degree of fluency at a low level of proficiency](/about/goal-of-exercism.md). 6 | 7 | Each track has lots of small exercises, providing many opportunities for practice and lots of small wins. 8 | Each exercise consists of a pre-written test suite, simulating Test-Driven Development, and providing a clear definition of "done". 9 | 10 | A track lives in its own repository. 11 | Working on the exercises themselves should be like working on any project in that programming language. 12 | Since it is part of the larger Exercism ecosystem, there are some conventions to follow, and some necessary Exercism-specific configuration. 13 | 14 | ## Request a new track 15 | 16 | If there is a programming language that you love or are curious about, but that we don't yet support on Exercism open an issue in the [exercism/request-new-language-track](https://github.com/exercism/request-new-language-track/issues) repository. 17 | We can chat about what it would take to add it. 18 | 19 | ## Contribute to an existing track 20 | 21 | If you want to help improve one of the existing language tracks, take a look at our [guide to getting involved](/contributing-to-language-tracks/README.md). 22 | 23 | ## Launch a track 24 | 25 | To include a track on the site we need user-facing documentation, some tooling, mentors, and—of course—exercises for people to solve. 26 | 27 | If you've requested a track and are ready to get it going, or if you've decided to adopt one of the unmaintained tracks, check out the [launch guide](/language-tracks/launch/README.md). 28 | 29 | ## Maintain a track 30 | 31 | Tracks tend to require some ongoing maintenance. 32 | We provide support when people ask questions, support new contributors, review pull requests, improve tooling, and add and improve exercises. 33 | We've written down some of the tips, tricks, and hard-earned lessons that we've picked up over the past few years in the [track maintainer](/maintaining-a-track/README.md) documentation. 34 | -------------------------------------------------------------------------------- /language-tracks/configuration/README.md: -------------------------------------------------------------------------------- 1 | # Configuration 2 | 3 | ## Track-level configuration 4 | 5 | The configuration for a language track lives in a file named `config.json` in the root of a repository. 6 | 7 | This is used by the website as well as a lot of the tooling in order to properly combine all the disparate language track repositories into a coherent experience and curriculum. 8 | 9 | ## Dependencies 10 | 11 | The `config.json` is used by [trackler][], which is a light wrapper around the entire Exercism curriculum, and [configlet][], which is the tool that we use to verify the configuration. 12 | 13 | ## Automated verification of `config.json` 14 | 15 | We have [automated linting of the track configuration][configlet-lint]. 16 | 17 | [configlet-lint]: /language-tracks/configuration/configlet.md 18 | [trackler]: https://github.com/exercism/trackler 19 | [configlet]: https://github.com/exercism/configlet 20 | -------------------------------------------------------------------------------- /language-tracks/configuration/configlet.md: -------------------------------------------------------------------------------- 1 | # Configlet 2 | 3 | You can download the latest release from the releases page in the [configlet repo](https://github.com/exercism/configlet/releases). 4 | 5 | ## Linting 6 | 7 | The `lint` command helps ensure that: 8 | 9 | 1. all exercises have a unique uuid 10 | 1. all exercises have a test suite 11 | 1. all exercises have a reference solution 12 | 1. all the `exercises` that are listed in the configuration have, in fact, been implemented 13 | 1. all implementations are listed in the configuration 14 | 1. exercises that the maintainers have decided to forego do not have an associated implemention 15 | 16 | A problem might be foregone for a number of reasons, typically because it's not a good fit for the language. 17 | 18 | ## Formatting 19 | 20 | The `fmt` command is used to normalize the JSON format for the `config.json` file as well as the `config/maintainers.json` file. 21 | This helps ensure that we don't get irrelevant, noisy diffs in these files. 22 | 23 | This is especially useful because we sometimes need to make changes across all of the language tracks at the same time. 24 | We tend to script these pull requests, and it's harder to review these when they include irrelevant whitespace changes. 25 | 26 | ## UUID Generation 27 | 28 | The `uuid` command makes it easy to generate a new UUID for an exercise that is being added. 29 | -------------------------------------------------------------------------------- /language-tracks/configuration/exercises.md: -------------------------------------------------------------------------------- 1 | # Exercise configuration 2 | 3 | The `exercises` consists of an array of objects, each of which defines the metadata for an exercise. 4 | 5 | ## The exercise object 6 | 7 | Each object consists of the following keys: 8 | 9 | * **uuid** (string) - a unique identifier across all Exercism tracks 10 | * **slug** (string) - a unique, human-readable identifier _within_ the track 11 | * **core** (boolean) - whether or not this exercise is part of the core set of exercises necessary to complete the track 12 | * **unlocked_by** (string) - the core exercise that an optional exercise depends on 13 | * **difficulty** (integer) - a rough estimate of the difficulty level of the exercise on a scale of 1 to 10. 14 | * **topics** (array of strings) - topics covered in this exercise 15 | 16 | The UUID must never change once the track has been added to the site. 17 | All other values can be updated. 18 | 19 | ### UUID 20 | 21 | This must be unique to this particular exercise implementation across all of Exercism's tracks, and must never change. 22 | [Configlet][configlet] has a `uuid` subcommand (`configlet uuid`), but you can use any UUID generator tool to create it. 23 | If you do use configlet make sure the configlet version agrees with the [latest configlet version](https://github.com/exercism/configlet/releases/latest). 24 | The UUID should be of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. 25 | 26 | ### Slug 27 | 28 | The slug is used in a lot of places: URLs, directory names, as options to commands on the command line, and more. 29 | It is a normalized, human-readable version of the exercise name and must be unique within a given track. 30 | In other words you wouldn't have two `clock` exercises in the same track, but you might have a `clock` exercise in lots of different language tracks. 31 | 32 | You can change the slug for an exercise. 33 | This will not break anything for people who have submitted solutions to the exercise, as long as the UUID remains the same. 34 | You'll need to make a few changes in the project outside of just editing the slug in the `config.json` file. 35 | Let `configlet lint .` guide you. 36 | 37 | ### Core 38 | 39 | Each track consists of a set of 8-20 core exercises. 40 | In order to complete the track, you must complete all of the core exercises. 41 | 42 | Each core exercise should ideally unlock a handful of optional exercises. 43 | 44 | For more about why we've structured the tracks in this way, read the [Progression](/about/conception/progression.md) document. 45 | 46 | ### Unlocked by 47 | 48 | Any exercise that is not a core exercise is optional. 49 | Almost all optional exercises should be unlocked by one of the core exercises (see [bonus](#user-content-bonus) below for exceptions). 50 | Set the value of `unlocked_by` to the slug of the core exercise that is the prerequisite for getting access to this exercise. 51 | 52 | #### Bonus 53 | 54 | Tracks may start with a few _bonus exercises_: unlocked alternatives to the initial track starting exercise. These alternatives will give users some means to continue should they wish to divert from the main track early in the progression, if they hit a [blocking scenario][track-blocking-progression] for example. Bonus exercises will be identified as non-core: `core: false` and out of the unlock sequence: `unlocked-by: null`. 55 | 56 | ### Difficulty 57 | 58 | We show the difficulty of an exercise on the website. 59 | This lets people filter and choose when they have a lot of optional exercises available to them. 60 | 61 | A rough estimate will do. 62 | Use a scale from 1 to 10. 63 | 64 | ### Topics 65 | 66 | We show the topics for an exercise on the website. 67 | This lets people optimize the learning experience to their own interests—skipping topics that they are not interested in, or that they already know a lot about, and doing deeper dives into topics that they're curious about. 68 | Take a look at the (non-exhaustive) [topics list][topics] for suggestions of topics to add. 69 | 70 | ## Deprecating exercises 71 | 72 | Deleting an exercise is a destructive action it would delete all users' solutions to that exercise. Instead, we allow exercises to be deprecated, users who have completed the exercise can access their existing solutions, those who have not will not see or be able to start the exercise. 73 | 74 | Deprecated exercises must have the following set in `config.json`: 75 | 76 | - **uuid** 77 | - **slug** 78 | - **deprecated** (boolean, true) 79 | 80 | All other fields in deperecated exercises should remain as is. 81 | 82 | [configlet]: /language-tracks/configuration/configlet.md 83 | [topics]: https://github.com/exercism/problem-specifications/blob/master/TOPICS.txt 84 | [track-blocking-progression]: https://github.com/exercism/v2-feedback/issues/36 85 | -------------------------------------------------------------------------------- /language-tracks/configuration/track.md: -------------------------------------------------------------------------------- 1 | # Track configuration 2 | 3 | ``` 4 | ./config.json 5 | ``` 6 | 7 | This file has the following keys: 8 | 9 | * **language** (string) the official name of the programming language. 10 | * **blurb** (string) a short, friendly intro to be used in the header of the landing page on the site. 11 | * **active** (boolean) whether the track is active on the site. 12 | * **test_pattern** (string) _(optional)_ a regex pattern that test filenames will match. It is used to determine which files will be visible on a problem's test-suite page on the exercism.io site. The default value used if this key is not present is `/test/i`. 13 | * **ignore_pattern** (string) _(optional)_ a regex pattern that will cause files matching it to not be served by the `exercism fetch` command. The default value used if this key is not present is `/example/i`. 14 | * **solution_pattern** (string) _(optional)_ a regex pattern that matches solution files in the track repository. If not present, it defaults to `/[Ee]xample/` 15 | * **foregone** (array of strings) a list of problem specification slugs that the track maintainers have decided not to implement. 16 | * **exercises** (array of objects) the metadata for implemented exercises. 17 | 18 | The format of the `exercises` array is described in detail [here](/language-tracks/configuration/exercises.md). 19 | -------------------------------------------------------------------------------- /language-tracks/documentation/for-consumers.md: -------------------------------------------------------------------------------- 1 | # Writing Language Track Documentation 2 | 3 | The user-facing documentation lives in the `docs/` directory in the language track repository. 4 | 5 | ## About 6 | 7 | ``` 8 | docs/ABOUT.md 9 | ``` 10 | 11 | The about page should be a short, friendly, colloquial introduction to the language. The intent is to entice people to try it out. 12 | 13 | ### Formatting guidelines for ABOUT.md 14 | 15 | We're optimizing the _About_ to work well on the track's landing page. In order to do this, we're adding some restrictions on the markdown allowed. In short, `ABOUT.md` should only use: 16 | 17 | * Bold 18 | * Italics 19 | * Links 20 | * Bullet lists 21 | * Number lists 22 | * Each sentence should be on its own line 23 | * Paragraphs separated by an empty line 24 | * Explicit
used to split a paragraph into lines without spacing between them (discouraged). 25 | 26 | ## Installation and setup 27 | 28 | ``` 29 | docs/INSTALLATION.md 30 | ``` 31 | 32 | If someone is going to use Exercism to ramp up in a new programming language, they are going to need to get their local environment set up so that they can solve the problems in that language. 33 | 34 | At the very minimum, people will need to know: 35 | 36 | 1. how to install the programming language on their machine 37 | 1. how to install any necessary dependencies 38 | 39 | 40 | ## How to run the tests 41 | 42 | ``` 43 | docs/TESTS.md 44 | ``` 45 | 46 | We also like to add some other goodies, for example: 47 | 48 | * **a short introduction about the language**. This helps entice people to start learning it. This should not go into too much detail, as it can link to more in-depth information. It should give a high-level idea of what kind of language it is, and what type of problems it's used to solve, or where it is typically used. The keyword here is *enticing*. We don't need to tell people everything, just get them curious enough to want to try it, or to read more about it. 49 | * **where to learn the basics**. If you're learning the language from scratch, what are some good resources that teach you about the language. Tutorials, websites, books, videos—we're looking for things that people would use to orient themselves and get a good introduction. This is often what you'd use *before* doing Exercism. 50 | * **references and resources**. As people work the exercises on Exercism, they'll probably want reference materials. Where can they find the documentation for the standard library? Are there any useful tools, such as linters or style guides? Are there forums or channels where people can meet other people and ask for help? 51 | 52 | This documentation gets included on the website on the page for each language track. You can browse the track documentation starting from [the main language page](http://exercism.io/languages). 53 | 54 | ## File Structure 55 | 56 | Everything that is specific to a particular programming language lives in the repository for that particular language track, making it easy for the people who maintain the track to manage it. 57 | 58 | Since all the language track documentation gets included on the site, it needs to be standardized. We've settled on the following file structure: 59 | 60 | ```bash 61 | . 62 | └── docs/ 63 |    ├── img/ 64 | │   ├── image-one.svg 65 | │   ├── image-two.png 66 | │   └── image-three.jpg 67 |    ├── ABOUT.md 68 |    ├── INSTALLATION.md 69 |    ├── LEARNING.md 70 |    ├── RESOURCES.md 71 |    └── TESTS.md 72 | ``` 73 | 74 | The mapping of topics to filenames goes like this: 75 | 76 | * `INSTALLATION.md` - how to install the language and any dependencies 77 | * `TESTS.md` - how to run the tests 78 | * `ABOUT.md` - short, enticing introduction to the language 79 | * `LEARNING.md` - where to get an introduction to the language if you're learning it for the first time 80 | * `RESOURCES.md` - references, tools, etc. 81 | 82 | Any images referenced in the markdown files need to live within the `docs/img` directory. If the directory doesn't exist, you can create it when you need it. 83 | 84 | When referring to the images in the markdown, use a path starting with `/docs` (note the slash) 85 | E.g., if you have an image named `docs/img/dropdown.png`, then you would reference it with: 86 | 87 | ``` 88 | ![](/docs/img/dropdown.png) 89 | ``` 90 | 91 | There are a number of variations on markdown image syntax. [This guide](https://daringfireball.net/projects/markdown/syntax#img) has more details. 92 | 93 | This will show up correctly when you browse the documentation within the repository on GitHub, and also when it is included on the Exercism website, where we rewrite the paths to refer to the correct API endpoint that serves the images. 94 | 95 | -------------------------------------------------------------------------------- /language-tracks/documentation/for-contributors.md: -------------------------------------------------------------------------------- 1 | # Contributing documentation 2 | 3 | You probably don't need a whole CONTRIBUTING.md file. Stick with the project README.md until that is getting crowded. 4 | 5 | This should contain a link to the [Exercism-wide contributing guide](https://github.com/exercism/docs/blob/master/contributing-to-language-tracks/README.md) and specific information about how to contribute to your language track: 6 | 7 | - how to get the project set up locally 8 | - how to run the tests 9 | - any conventions to follow e.g. style guide etc 10 | -------------------------------------------------------------------------------- /language-tracks/documentation/introductory-copy.md: -------------------------------------------------------------------------------- 1 | # Introductory copy 2 | 3 | The aim of the introductory copy is to entice someone into wanting to try the language out. 4 | 5 | We're not looking for Wikipedia-level detail. 6 | 7 | ## Introductory blurb (~30 words) 8 | 9 | ``` 10 | config.json 11 | ``` 12 | 13 | We need a very short plain-text blurb of about 30 words (a couple of sentences). 14 | 15 | The goal is to give someone a really quick feel for what the language is about and why it might appeal to them. 16 | 17 | The blurb is stored in the `config.json`, in a top-level key named `"blurb"`. 18 | 19 | ## About (~120 words) 20 | 21 | ``` 22 | docs/ABOUT.md 23 | ``` 24 | 25 | The blurb is closely followed by an "about" section on the main track page. 26 | 27 | This provides a bit more detail about the language. 28 | It might talk about its history, design goals, or about what the language is a great fit for, etc. 29 | This should be 70-120 words split over 1-3 paragraphs. This text should be a friendly, genuine sales pitch for why someone should learn a language. 30 | 31 | It should not be an in-depth introduction, and it should not be a quote from another source, though it can certainly point people to other sources if they want to learn more. 32 | It can be in markdown format, but should only contain links and emphasis (bold, italic). 33 | 34 | For inspiration, check out the `ABOUT.md` files from [the Go track](http://github.com/exercism/go/tree/master/docs/ABOUT.md) and [the R track](http://github.com/exercism/r/tree/master/docs/ABOUT.md). 35 | 36 | ## Code snippet 37 | 38 | Next to the "About $LANGUAGE" on the track page, there will be a small code snippet. 39 | 40 | The goal of the snippet is to give people a quick idea of what the syntax of the language looks like. 41 | It doesn't need to be sophisticated, and it doesn't need be be copy/pastable into a REPL. 42 | 43 | It should be **10 lines** maximum, and no more than **40 columns** wide. 44 | -------------------------------------------------------------------------------- /language-tracks/exercises/README.md: -------------------------------------------------------------------------------- 1 | # Exercises 2 | 3 | Each exercise should be implemented idiomatically for the language in question. 4 | Keep the [goals of Exercism][goal] in mind when considering new exercises or changes to existing ones. 5 | 6 | **Exercises should not enforce a single way to solve the problem, if possible.** The more interesting exercises allow several approaches, and create rich opportunities for discussing trade-offs when people submit their solutions. 7 | 8 | Sometimes it's tempting to expand the exercise to cover more cases or a broader topic. 9 | 10 | This might be the right thing to do. Or it might add more work with little additional value. The right answer might also be to invent a new exercise to cover the proposed ideas. Consider whether this should be discussed just among the maintainers of a single language track, or whether it should be raised to all track maintainers via an issue in the [problem-specifications][] repository. 11 | 12 | Don't be afraid to skip (or 'forego') exercises that don't make sense in the language, or that are not particularly interesting. 13 | 14 | For more nitty-gritty details about what to consider concerning exercises, see [reviewing pull requests](/you-can-help/review-pull-requests.md). 15 | 16 | ## Files 17 | 18 | Each exercise has corresponding metadata in the track's [`config.json`][config-json]. Use the slug to define the directory name for the exercise. 19 | 20 | Further, the exercise should contain: 21 | 22 | * a test suite containing automated tests that define the requirements for completing the exercise. 23 | * a README describing the exercise to the user, along with any hints or instructions to help them solve it. 24 | * a `.meta` directory containing any files that are required to define the exercise, but which should not be delivered to the user. 25 | 26 | ``` 27 | exercises/ 28 | └── foo/ 29 | ├── .meta 30 | │   ├── example-solution.ext # (required) 31 | │   ├── description.md # (maybe) 32 | │   ├── metadata.yml # (maybe) 33 | │   ├── hints.md # (optional) 34 | │   └── readme.go.tmpl # (optional) 35 | ├── hello-world-test.ext 36 | ├── hello-world.ext 37 | └── README.md # (generated) 38 | ``` 39 | 40 | The `.meta` directory may contain: 41 | 42 | * _(required)_ a reference solution which can be used to verify the soundness of the exercise test suite. 43 | * _(optional)_ a `readme.go.tmpl`, used to generate the README if it does not use the track's general exercise README template. 44 | * _(optional)_ a `hints.md` file, where hints to the user about the exercise can be added to be included in the exercise README. If you have a `readme.go.tmpl` file, you can include the hints directly in the template. The `hints.md` file is useful if the exercise relies on the track-level template. 45 | * _(it depends)_ a problem specification. These files are only necessary if the exercise is not based on a specification from the [shared pool of problem specifications][problem-specifications]. 46 | * `metadata.yml` 47 | * `description.md` 48 | 49 | Read more about [exercise READMEs][readmes], [test suites][tests], and the [reference solution][solution]. 50 | 51 | [problem-specifications]: http://github.com/exercism/problem-specifications 52 | [goal]: /about/goal-of-exercism.md 53 | [config-json]: /language-tracks/configuration/README.md 54 | [readmes]: /language-tracks/exercises/anatomy/readmes.md 55 | [tests]: /language-tracks/exercises/anatomy/test-suites.md 56 | [solution]: /language-tracks/exercises/anatomy/reference-solution.md 57 | -------------------------------------------------------------------------------- /language-tracks/exercises/anatomy/README.md: -------------------------------------------------------------------------------- 1 | # Anatomy of an exercise 2 | 3 | Exercises on Exercism typically are an implementation of an existing problem, as described in the [problem-specifications](https://github.com/exercism/problem-specifications) repository. 4 | 5 | Each exercise must be implemented in a directory within the `./exercises` which can be found in the root of the repository. 6 | 7 | The directory must be named with kebab-case (lowercase, hyphenated). 8 | All the files within it can be named to match the conventions of the language. 9 | 10 | In order to integrate with the command-line client and the website, a few things need to be in place: 11 | 12 | - an [exercise README](readmes.md) 13 | - a [test suite](test-suites.md) 14 | - a [reference solution](reference-solution.md) 15 | 16 | If the exercise needs any supporting files such as boilerplate, header files, etc, these can be added in the exercise directory tree. 17 | They will automatically be delivered along with the test suite and README. 18 | -------------------------------------------------------------------------------- /language-tracks/exercises/anatomy/readmes.md: -------------------------------------------------------------------------------- 1 | # READMEs 2 | 3 | Exercise READMEs are generated and committed to the repository. 4 | 5 | ## Generating a README 6 | 7 | ### Setup 8 | 9 | Install [configlet][]. You will need version 3.0.0 or higher. 10 | 11 | If any of the exercises in the track are based on problems in the [problem-specifications][] repository, then you will 12 | need to have a copy of that repository locally on disk, in the same directory as your track. 13 | 14 | ``` 15 | . 16 | ├── the-track/ 17 | └── problem-specifications/ 18 | ``` 19 | 20 | ### Generation 21 | 22 | Assuming that you are in the root of the track repository, generate the README for an exercise with the slug `foo` using the following command: 23 | 24 | ``` 25 | configlet generate . --only foo 26 | ``` 27 | 28 | The command is build up as follows: 29 | 30 | * `configlet` - the name of the tool 31 | * `generate` - the subcommand that directs the tool to generate READMEs 32 | * `.` - the path to the root of the repository 33 | * `--only foo` - a flag specifying which exercise to generate. If you leave off the flag, the tool will generate all the READMEs. 34 | 35 | 36 | ## The README Template 37 | 38 | Each track has a default template in `$TRACK_ROOT/config/exercise-readme.go.tmpl`, and an exercise may override that template by creating a `$TRACK_ROOT/exercises/$SLUG/.meta/readme.go.tmpl` file. 39 | 40 | The template is written using Go's [text/template][text-template] package. 41 | 42 | There are a number of values available in the template: 43 | 44 | `.Spec` represents the problem specification, which is either a shared specification from [problem-specifications][], or a custom specification found in the exercise's `.meta` directory. The following values on `.Spec` can be referenced within the template: 45 | 46 | - `.Spec.Slug` - the exercise's slug 47 | - `.Spec.Name` - the wordified slug 48 | - `.Spec.MixedCaseName` - the name converted to mixed case, e.g. _Hello World_ becomes `HelloWorld` 49 | - `.Spec.SnakeCaseName` - the name converted to snake case, e.g. _Hello World_ becomes `hello_world` 50 | - `.Spec.Description` - the contents of the optional `$TRACK_ROOT/exercises/$SLUG/.meta/description.md` file 51 | - `.Spec.Source` - a textual description of where the idea for the exercise came from (optional) 52 | - `.Spec.SourceURL` - a link to something about the source (optional) 53 | - `.Spec.Credits` - combines source and source_url into a readable bit of metadata 54 | 55 | In addition to the values on `.Spec`, there are two additional bits of text that can be included: 56 | 57 | - `.Hints` - the contents of the optional `$TRACK_ROOT/exercises/$SLUG/.meta/hints.md` file. 58 | - `.TrackInsert` - the contents of the `$TRACK_ROOT/config/exercise-readme-insert.md` file. 59 | 60 | ### Go's Text/Template Package 61 | 62 | You don't need much of the Go text/template language. The three things that are used in the default template are probably all you need: 63 | 64 | * `{{ .Something }}` outputs a value 65 | * `{{ with .Something }} ... {{ . }} ... {{ end }}` will conditionally output contents between the `with` and `end` markers if `.Something` is not empty. To refer to the value of `.Something`, use `{{ . }}`. The `...` represents any text that you want to output there. 66 | * `{{-` and `-}}` remove preceding and following whitespace. 67 | 68 | ### Default Template 69 | 70 | The default contents of `$TRACK_ROOT/config/exercise-readme.go.tmpl` is below. 71 | 72 | ``` 73 | # {{ .Spec.Name }} 74 | 75 | {{ .Spec.Description -}} 76 | {{- with .Hints }} 77 | {{ . }} 78 | {{ end }} 79 | {{- with .TrackInsert }} 80 | {{ . }} 81 | {{ end }} 82 | {{- with .Spec.Credits -}} 83 | ## Source 84 | 85 | {{ . }} 86 | {{ end }} 87 | ## Submitting Incomplete Solutions 88 | It's possible to submit an incomplete solution so you can see how others have completed the exercise. 89 | ``` 90 | 91 | ## Philosophical Considerations 92 | 93 | ### Description 94 | 95 | The problem descriptions in the [problem-specifications][problem-specifications] repository tread a very fine line between useful ambiguity and confusing vagueness. Because the shared problem description is the same whether you're solving the problem in C++ or in Lua, it needs to be high-level enough to allow for the syntactic, semantic, and philosophical differences in the various languages. 96 | 97 | Having said that, each track is free to write a more specific description if they want to by creating their own `description.md` file and placing it in the exercise's `.meta` directory. 98 | 99 | ### Track Hints 100 | 101 | The `$TRACK_ROOT/config/exercise-readme-insert.md` gets included in _all_ the exercise READMEs for the track, and mustn't refer to specific problems or files. It should contain helpful, generic information about solving an exercism problem in the language of the track, for example hints about how to run the tests or where to get help. 102 | 103 | ### Exercise Hints 104 | 105 | Anything that is specific to just one exercise, should be added to the `$TRACK_ROOT/exercises/$SLUG/.meta/hints.md` file. 106 | 107 | [problem-specifications]: https://github.com/exercism/problem-specifications/tree/master/exercises 108 | [configlet]: https://github.com/exercism/configlet 109 | [text-template]: https://golang.org/pkg/text/template/ 110 | -------------------------------------------------------------------------------- /language-tracks/exercises/anatomy/reference-solution.md: -------------------------------------------------------------------------------- 1 | # Reference Solution 2 | 3 | The reference solution is typically named something with `example` or `Example` in the path, but you can define a pattern for the reference solutions in the `config.json`, defined by the `solution_pattern` key. 4 | 5 | The solution does not need to be particularly great code as it is only used to verify that the exercise is coherent. 6 | 7 | If you change the test suite, then make sure the reference solution is fixed to pass the updated tests. 8 | -------------------------------------------------------------------------------- /language-tracks/exercises/anatomy/test-suites.md: -------------------------------------------------------------------------------- 1 | At the most basic level, Exercism is all about the tests. They drive the user's implementation forward and tell them when the exercise is complete. 2 | 3 | The utmost care and attention should be used when adding or making changes to the tests for an exercise. When implementing an exercise test suite, we want to provide a good user experience for the people writing a solution to the exercise. People should not be confused or overwhelmed. 4 | 5 | We simulate Test-Driven Development (TDD) by implementing the tests in order of increasing complexity. We try to ensure that each test either 6 | 7 | - helps triangulate a solution to be more generic, or 8 | - requires new functionality incrementally. 9 | 10 | Above all, a good test suite adheres to the conventions of the language and the testing idioms of the framework used in the track. 11 | 12 | The characteristics of a good individual test are: 13 | 14 | - a clear name or description that reveals the intent of the test 15 | - a minimal amount of setup 16 | - Temporary variables should be avoided unless they add to the test's clarity. 17 | - Well named test helpers can be employed to encapsulate shared setup between tests. 18 | - Test helpers should be extremely simple, and branching logic inside a helper is to be avoided. 19 | - a manageable increase in complexity from the previous passing test 20 | - introduces a single new requirement 21 | - a minimal number of expectations required to specify the change (one expectation is preferred) 22 | - a readable and understandable failure message 23 | - does not duplicate the expectations of another test 24 | 25 | Many testing frameworks randomize the order in which tests are run. Under normal circumstances this is desirable, since it helps enforce tests that are independent of each other. In the context of Exercism, however, this can be confusing. When someone begins to solve an exercise, getting all the failures for all the tests in random order can make it hard to know where to begin solving the problem. 26 | 27 | In order to provide a better user experience, some language tracks only leave the first test in an exercise test suite active. All subsequent tests are marked as "skipped" or "pending" using whatever method or directive that is provided by the testing framework. This means that the person solving the exercise must manually edit the test suite to activate the tests one by one as they write their solution. 28 | 29 | Additionally, this has implications for Continuous Integration (CI), as the test script must change the test file in order to activate all the tests. 30 | 31 | The test suite of an exercise should be guided by the common specifications laid out by the `canonical-data.json` file of each exercise in [problem-specifications](https://github.com/exercism/problem-specifications) if it is available. The specifications there provide good defaults for: 32 | 33 | - the order of the tests 34 | - the descriptions of the tests 35 | - the inputs and expected outputs of each test 36 | 37 | Feel free to implement a test generator for your track if you feel it would aid in creating test suites from `canonical-data.json`. 38 | 39 | The specifications in `canonical-data.json` are the strongly recommended defaults, but if you have a good reason (language idioms, etc) then don't hesitate to deviate from them. 40 | 41 | If there is no `canonical-data.json` file for the exercise then we recommend using https://tracks.exercism.io/ to find other tracks that have implemented the exercise. 42 | -------------------------------------------------------------------------------- /language-tracks/exercises/versioning.md: -------------------------------------------------------------------------------- 1 | 2 | ### Exercise Versioning 3 | 4 | It's only when we get a bunch of people having conversations about the 5 | solutions that we really discover what makes a problem interesting, and 6 | in what way it can be improved. 7 | 8 | Some changes to the test suites will invalidate existing solutions that people 9 | have submitted. 10 | 11 | We think this is totally fine, however sometimes people start leaving feedback 12 | saying _this doesn't pass the tests_. This is technically true, but since the 13 | solution passed the tests at the time it was written, it's generally more 14 | useful to just discuss the code as it is, rather than enforce strict 15 | adherence to the most recent version of the tests. 16 | 17 | Some language tracks have implemented a simple, manual versioning system to 18 | help avoid unnecessary discussions about failing the current test suites. 19 | 20 | If the exercise is versioned, then the test suite will probably have a 21 | _book-keeping_ type test at the very bottom that asserts against a value in 22 | the reference solution. If the change you're making is backwards-incompatible, 23 | then please increment the version in both the test suite and the reference 24 | solution. 25 | -------------------------------------------------------------------------------- /language-tracks/launch/README.md: -------------------------------------------------------------------------------- 1 | # Launching a new language track 2 | 3 | At this point you should [have a repository to work in](https://github.com/exercism/request-new-language-track/issues). 4 | 5 | The next steps are roughly: 6 | 7 | - [ ] Select programming language variant (if applicable) 8 | - [ ] Select testing framework 9 | - [ ] Write first exercise 10 | - [ ] Plan initial core + optional exercises 11 | - [ ] Add the track to the site as inactive 12 | - [ ] Request a track icon 13 | - [ ] Write "getting started" instructions for people using the track 14 | - [ ] Launch! 15 | - [ ] Prepare for open source contributions from strangers 16 | 17 | ## Installation and dependencies 18 | 19 | Before you can start implementing exercises, you'll need to make some decisions. 20 | 21 | 1. Which variant of the programming language to support (if there are multiple). 22 | 1. Which testing framework to use. 23 | 24 | All of the exercises are based on providing a failing test suite for people to run and make pass, so we need to pick a testing framework. 25 | If there are multiple testing frameworks available, we'll need to figure out which one is the best fit. 26 | 27 | ### Considerations 28 | 29 | 1. Ease of getting started. 30 | 1. Cross-platform support (MacOS, Linux, Windows). 31 | 32 | For people who are going to be doing the exercises, it's important to get them up and running as quickly as possible. 33 | 34 | In general we prefer tools in the standard library if they're available, and if not we aim for a third party library that is widely used. 35 | If there is a choice between several common libraries, then consider a few factors: 36 | 37 | * Is one of them easier to install? 38 | * Is one of them easier to get help with or search for resources about? 39 | * Is one of them simpler than the other either in syntax or conceptually? 40 | 41 | Remember that all Exercism exercises are by nature very small, so there's no need for the complexity that real-world projects sometimes require. 42 | 43 | ### Document the decisions 44 | 45 | As you make these decisions, document them in the README.md of the repository for 46 | contributors and future maintainers. In particular, when someone submits a contribution 47 | that goes against one of these decisions, it's very helpful to be able to point to not just 48 | the conclusion, but also a bit about why that decision was made. That makes it easier to 49 | decide whether to just close the issue or pull request from the contributor, or whether 50 | it's time to re-evaluate the decision based on new information. 51 | 52 | The harder the decision was to make, the more important it is to document it thoroughly. 53 | (e.g. What trade-offs did you consider? What tipped your gut feeling in one direction or the other? What sealed the deal?) 54 | 55 | ## Implement the first exercise 56 | 57 | The first exercise will be a very simple "Hello, World!". 58 | In some rare cases, this might not be the best choice. 59 | If so let's discuss how to proceed. 60 | 61 | The point of this exercise is to quickly make sure that everything is wired together correctly. 62 | 63 | This will confirm that the user has the programming environment installed correctly, that they know how to run the tests, and are able to make it pass. 64 | Beyond this, it also ensures that they have the Exercism command-line client (CLI) installed and configured, and that the site delivers the correct files for the exercise without delivering any unnecessary artifacts. 65 | Lastly it ensures that the user is familiar with the cycle of downloading an exercise using the CLI, solving a problem in their local development environment, and submitting their solution back to the site. 66 | 67 | In other words, this isn't really about learning anything about the language itself yet. 68 | We're aiming for something dead simple. 69 | 70 | See [this documentation for details](/language-tracks/launch/first-exercise.md). 71 | 72 | This is also probably going to be the hardest part of getting the track repository set up right, as there are a lot of moving pieces. 73 | 74 | ## Set up Continuous Integration 75 | 76 | Once you have one exercise set up, it's worth looking at [tooling and continuous integration](/language-tracks/launch/tooling-and-ci.md). 77 | 78 | ## Plan initial core + optional exercises 79 | 80 | The best place at the moment to help think this through is going to be the #project-track-anatomy channel in the exercism-team slack. 81 | 82 | There are a ton of considerations to take into account in terms of making the best possible experience for those working through the track, as well as the mentors who will be providing feedback. 83 | 84 | We're in the process of formalizing and documenting a lot of this, so more information will be available in the coming months. 85 | 86 | ## Prepare for launch 87 | 88 | Each track has a landing page on the site. 89 | E.g. (when logged out) https://exercism.io/tracks/go 90 | 91 | The page is meant to entice people into wanting to try the language out. 92 | 93 | There are four things that we need (details below): 94 | 95 | - an icon for the track 96 | - a short blurb for the header section 97 | - an "about" section with a bit more detail 98 | - a code snippet that gives a visual impression of what the language syntax looks like 99 | - maintainer bios 100 | 101 | In order to design an icon for the site open a new issue in the [exercism/website-icons](https://github.com/exercism/website-icons/issues) repository, answering the following questions: 102 | 103 | * Does the language have an official logo? If so 104 | - please include a link to an example 105 | - please list the attribution rights of that logo 106 | * Does the language have an unofficial logo? If so 107 | - please explain the ways in which people use the unofficial logo 108 | - please include a link to an example 109 | - please list the attribution rights of that logo 110 | 111 | For the blurb, about section, and code snippet please see the [documentation about introductory copy](https://github.com/exercism/docs/blob/master/language-tracks/documentation/introductory-copy.md). 112 | 113 | The maintainer bios go in the [maintainer config](/maintaining-a-track/maintainer-configuration.md). 114 | The goal of the bio is to give people a little bit of insight into your background with the language and why you are involved with the track on Exercism. 115 | As you bring on new co-maintainers, have them add themselves to the file as well. 116 | 117 | ## Write "getting started" instructions for people using the track 118 | 119 | We need to guide people through the process of getting their development environment working, and make sure they know how to run the tests. 120 | 121 | As a bonus, we could provide some links to learning resources for people who are completely new to the language, and resources that come in handy while they're developing. 122 | 123 | More on this in the [documentation about documentation](https://github.com/exercism/docs/blob/master/language-tracks/documentation/for-consumers.md). 124 | 125 | ## Launch! 126 | 127 | In order to launch you'll need to have a handful of people who can show up most days to provide feedback on the site. 128 | 129 | Then flip the `active` switch in `config.json` to true, and the track will show up on the homepage. 130 | 131 | ## Prepare for open-source contributions from strangers 132 | 133 | At this point you should be able to accept contributions from strangers. 134 | Write some [contributing documentation](/language-tracks/documentation/for-contributors.md). 135 | 136 | If there are exercises that you wish to include in the track, but have not yet implemented, open issues for each exercise. 137 | 138 | Other things to consider: 139 | 140 | - Is there a style guide for your programming language? 141 | - Are these styles encouraged or enforced? 142 | - Are there any conventions that we should adopt on this track for the sake of consistency? 143 | - Can we enforce these? 144 | - Is there a linter? Are there many? Should we use one? 145 | - Is there a common convention for filenames? If not, what should our convention be? 146 | 147 | It could be worth opening separate issues for the things you wish to tackle. 148 | 149 | Once you've gotten the track into a state where others can contribute, update the 150 | README to provide guidelines for contribution. 151 | -------------------------------------------------------------------------------- /language-tracks/launch/beta.md: -------------------------------------------------------------------------------- 1 | # Beta testing your track 2 | 3 | We still need to work out the details of preview/beta in the new site. 4 | It will be possible to use the Exercism CLI to download exercises and submit solutions, even though the track is not yet live on the site. 5 | -------------------------------------------------------------------------------- /language-tracks/launch/finding-mentors.md: -------------------------------------------------------------------------------- 1 | # Finding mentors 2 | 3 | This is going to be a huge deal. 4 | We're putting together a ton of resources about it, and will update this when we know more. 5 | -------------------------------------------------------------------------------- /language-tracks/launch/first-exercise.md: -------------------------------------------------------------------------------- 1 | # Implement the first exercise 2 | 3 | This will likely be a program that outputs _Hello, World!_. 4 | In some rare cases, this might not be the best choice. 5 | If so let's discuss how to proceed. 6 | 7 | The point of this exercise is to quickly make sure that everything is wired together correctly. 8 | This will confirm that the user has the programming environment installed correctly, that they know how to run the tests, and are able to make it pass. 9 | Beyond this, it also ensures that they have the Exercism command-line client (CLI) installed and configured, and that the site delivers the correct files for the exercise without delivering any unnecessary artifacts. 10 | Lastly it ensures that the user is familiar with the cycle of downloading an exercise using the CLI, solving a problem in their local development environment, and submitting their solution back to the site. 11 | 12 | In other words, this isn't really about learning anything about the language itself yet. 13 | We're aiming for something dead simple. 14 | 15 | This section assumes that the exercise is a literal _Hello, World!_ program based on the [Hello World problem specification](https://github.com/exercism/problem-specifications/blob/master/exercises/hello-world/). 16 | 17 | We're going to need: 18 | 19 | * a directory for the exercise 20 | * a test suite 21 | * a (complete) reference solution 22 | * a stub (incomplete) solution 23 | * a README (generated) 24 | * some configuration 25 | 26 | ## Create the directory 27 | 28 | Each exercise gets its own directory within the `exercises` directory. 29 | Create a directory named `hello-world`. 30 | 31 | ``` 32 | exercises/hello-world/ 33 | ``` 34 | 35 | ## Write the test suite 36 | 37 | The typical implementation of Hello World is [described in the canonical-data.json](https://github.com/exercism/problem-specifications/blob/master/exercises/hello-world/canonical-data.json) file. 38 | There is usually just one test, and it expects the string "Hello, World!". 39 | 40 | The test suite can live in a file directly in the `hello-world` directory, or you can create subdirectories if that makes sense for the language. E.g. in Java convention would put the test suite in `exercises/hello-world/src/test/java/HelloWorldTest.java`. 41 | 42 | Do whatever is idiomatic for the lanugage, but keep it as simple as reasonably possible. 43 | 44 | The test should be failing at this point. 45 | 46 | ## Write the reference solution 47 | 48 | Write a solution that passes this test. 49 | This is not going to be delivered to the user, it's only used to verify that the test suite is in good shape. 50 | 51 | Once it's working, copy the reference solution into a directory called `.meta` within the `hello-world` directory. 52 | This might not ultimately be where the reference solution lives, but for now it's a good start. 53 | 54 | There are two common strategies for naming the reference solution file so it is identifiable as such. 55 | First, you can give the file a specific name, e.g. `example-solution.ext`. 56 | Or, you can name the file the way you would in a real program (e.g. `hello-world.ext`), and use the containing path to identify it as the reference solution (e.g. (`solution/hello-world.ext`). 57 | 58 | Here's what your exercise directory might look like at this point. 59 | 60 | ``` 61 | exercises/ 62 | └── hello-world 63 | ├── .meta 64 | │   └── reference 65 | │   └── hello-world.ext 66 | ├── hello-world.ext 67 | └── hello-world-test.ext 68 | ``` 69 | 70 | ## Implement the stub solution 71 | 72 | The stub solution should be the reference solution, but with the actual "Hello, World!" missing. 73 | People should not have to worry about how to write the basic syntax, only fill in the blank. 74 | 75 | This is the file that the test suite should be looking for by default. 76 | 77 | If you run the tests now, they should be failing again. 78 | 79 | Eventually we're going to need some tooling that will let us run the test suite against the reference solution without stomping on any existing files, but don't worry about that quite yet. 80 | 81 | ## Create the README 82 | 83 | The README gets generated from a few different pieces. 84 | At minimum you'll need: 85 | 86 | - the README template 87 | - a local copy of the problem-specifications repository 88 | - the Configlet tool 89 | 90 | These are described below. 91 | You can also find more detail in the reference documentation about [exercise readmes](https://github.com/exercism/docs/blob/master/language-tracks/exercises/anatomy/readmes.md). 92 | 93 | ### The README template 94 | 95 | You should have a `config` directory at the root of your repository, containing a file named `exercise_readme.go.tmpl`. 96 | If you don't, then your repository might have been bootstrapped before we introduced the README templates. 97 | You can copy whatever you're missing from the [exercism/request-new-language-tracks](https://github.com/exercism/request-new-language-track/tree/master/config) repository, which we use to bootstrap new track repositories. 98 | 99 | By default the template uses metadata from the problem-specifications repository to put together the README. 100 | It can include other stuff, too, but for now just get the basics wired together. 101 | 102 | ### The problem specification 103 | 104 | Clone the [problem specifications repository](https://github.com/exercism/problem-specifications). 105 | Configlet expects the track repository to live side-by-side with the problem-specifications repository. 106 | 107 | ``` 108 | . 109 | ├── your-track 110 | │   └── exercises 111 | │   └── hello-world 112 | │   ├── .meta 113 | │   │   └── reference 114 | │   │   └── hello-world.ext 115 | │   └── hello-world-test.ext 116 | └── problem-specifications 117 | └── exercises 118 | └── hello-world 119 | ├── canonical-data.json 120 | ├── description.md 121 | └── metadata.yml 122 | ``` 123 | 124 | It's possible to override this location if you need to. 125 | 126 | ### The Configlet tool 127 | 128 | Download the [latest release of Configlet](https://github.com/exercism/configlet/releases/latest), extract the archive, and put it in your PATH. 129 | 130 | Generate the README for the exercise with the command: 131 | 132 | ``` 133 | configlet generate --only hello-world 134 | ``` 135 | 136 | From within the track repository the command would be: 137 | 138 | ``` 139 | configlet generate . --only hello-world 140 | ``` 141 | 142 | ### Exercise configuration 143 | 144 | The track has a `config.json` file, which contains an empty `"exercises"` array. 145 | You'll need to add an object to the array following the details the [exercise configuration](/language-tracks/configuration/exercises.md) docs. 146 | 147 | Verify the configuration by running `configlet lint .`. 148 | You may need to add some [track-level configuration](/language-tracks/configuration/track.md). 149 | 150 | Once `lint` is error free, run `configlet fmt .`, this will format the configuration files `config.json` and `maintainers.json`. Formatting will ensure that both files have consistent JSON syntax and indentation. Finally, formatting normalizes and alphabetizes the exercise topics within `config.json`. 151 | -------------------------------------------------------------------------------- /language-tracks/launch/landing-page.md: -------------------------------------------------------------------------------- 1 | # Prepare the track for the site 2 | 3 | ## Language track icon 4 | 5 | In order to design an icon for the site open a new issue in the [exercism/website-icons](https://github.com/exercism/website-icons/issues) repository, answering the following questions: 6 | 7 | * Does the language have an official logo? If so 8 | - please include a link to an example 9 | - please list the attribution rights of that logo 10 | * Does the language have an unofficial logo? If so 11 | - please explain the ways in which people use the unofficial logo 12 | - please include a link to an example 13 | - please list the attribution rights of that logo 14 | 15 | ## Introductory copy 16 | 17 | Each track has a landing page on the site. 18 | E.g. https://v2.exercism.io/tracks/go 19 | 20 | The page is meant to entice people into wanting to try the language out. 21 | 22 | There are three things that we need: a short blurb for the header section, an "about" section with a bit more detail, and a code snippet that gives a visual impression of what the language syntax looks like. 23 | 24 | For details on each of these see the full [documentation about introductory copy](https://github.com/exercism/docs/blob/master/language-tracks/documentation/introductory-copy.md). 25 | 26 | ## User-facing documentation 27 | 28 | We need to guide people through the process of getting their development environment working, and make sure they know how to run the tests. 29 | 30 | As a bonus, we could provide some links to learning resources for people who are completely new to the language, and resources that come in handy while they're developing. 31 | 32 | More on this in the [documentation about documentation](https://github.com/exercism/docs/blob/master/language-tracks/documentation/for-consumers.md). 33 | 34 | ## Maintainer bios 35 | 36 | Write a short bio for yourself, and add it to the [maintainer config](/maintaining-a-track/maintainer-configuration.md). 37 | As you bring on new co-maintainers, have them add themselves to the file as well. 38 | -------------------------------------------------------------------------------- /language-tracks/launch/open-issues.md: -------------------------------------------------------------------------------- 1 | # Open issues 2 | 3 | We've found that it's useful to have about 10 open issues at any time that someone can come in without any context about the project and contribute to. 4 | 5 | That might be as part of [Open Source Friday](https://opensourcefriday.com/), or a short-term campaign like [Hacktoberfest](https://hacktoberfest.digitalocean.com/) or [24 Pull Requests](https://24pullrequests.com/), or just something that you can share on your social network now and then to see if you can pull in new faces. 6 | 7 | Label these with "good first patch" and link to this search from your README. 8 | 9 | ## What to include 10 | 11 | Without being familiar with the project, the reader should understand 12 | 13 | - what problem the issue is trying to address 14 | - what needs to be done to close the issue 15 | - how to get started 16 | 17 | In this case we're adding more exercises so we can launch the new track, we're asking them to submit a pull request that implements the exercise, and we can point to: 18 | 19 | - the problem-specification for this exercise 20 | - our [guide to implementing an exercise from specification](https://github.com/exercism/docs/blob/master/you-can-help/implement-an-exercise-from-specification.md). 21 | - the track README with details about getting set up to contribute 22 | 23 | ## Bulk issues 24 | 25 | There's a command-line tool, [Hub](http://github.com/github/hub), which makes it easy to prepare a template issue and submit issues in bulk. 26 | You can also access the [GitHub API directly](https://developer.github.com/v3/issues/#create-an-issue), or by using an API client. 27 | 28 | -------------------------------------------------------------------------------- /language-tracks/launch/preview-mode.md: -------------------------------------------------------------------------------- 1 | # Preview mode 2 | 3 | We haven't figured out the details of this one yet. 4 | 5 | For now, if you're ready to put the track into preview mode, open an issue about it in your repository and mention @kytrinyx and we'll figure it out together. 6 | -------------------------------------------------------------------------------- /language-tracks/launch/tooling-and-ci.md: -------------------------------------------------------------------------------- 1 | # Tooling and continuous integration 2 | 3 | We typically implement a track test suite that can run both locally and on Travis CI. 4 | The track test suite should verify that each exercise makes sense, by running the exercise tests against the example solution. 5 | 6 | **Definition of terms** 7 | 8 | - **exercise test suite**: the test suite that is delivered to Exercism users as part of an Exercism exercise 9 | - **track test suite**: the test suite that helps ensure that all of the exercise test suites in a language track are solvable 10 | 11 | **Background** 12 | 13 | When implementing an exercise test suite, we want to provide a good user experience for the people writing a solution to the exercise. People should not be confused or overwhelmed. 14 | 15 | In most Exercism language tracks, we simulate Test-Driven Development (TDD) by implementing the tests in order of increasing complexity. We try to ensure that each test either 16 | 17 | - helps triangulate a solution to be more generic, or 18 | - requires new functionality incrementally. 19 | 20 | Many test frameworks will randomize the order of the tests when running them. This is an excellent practice, which helps ensure that subsequent tests are not dependent on side effects from earlier tests. However, in order to simulate TDD we want tests to run *in the order that they are defined*, and we want them to *fail fast*, that is to say, as soon as the test suite encounters a failure, we want the execution to stop. This ensures that the person implementing the solution sees only one error or failure message at a time, unless they make a change which causes prior tests to fail. 21 | 22 | This is the same experience that they would get if they were implementing each new test themselves. 23 | 24 | Most testing frameworks do not have the necessary configuration options to get this behavior directly, but they often do have a way of marking tests as _skipped_ or _pending_. The mechanism for this will vary from language to language and from test framework to test framework. 25 | 26 | Whatever the mechanism—functions, methods, annotations, directives, commenting out tests, or some other approach—these are changes made directly to the test file. The person solving the exercise will need to edit the test file in order to "activate" each subsequent test. 27 | 28 | Any tests that are marked as skipped will not be verified by the track test suite unless special care is taken. 29 | 30 | Additionally, in some programming languages, the name of the file containing the solution is hard-coded in the test suite, and the example solution is not named in the way that we expect people to name their files. 31 | 32 | We will need to temporarily (and programmatically) edit the exercise test suites to ensure that all of their tests are active. We may also need to rename the example solution file(s) in order for the exercise test suite to run against it. 33 | 34 | **Avoiding accidental git check-ins** 35 | 36 | It's important that if we rewrite files in any way during a test run, that these changes do not accidentally get checked in to the git repository. 37 | 38 | Therefore, many language tracks write the track test suite in such a way that it _copies_ the exercise to a temporary location outside of the git repository before editing or rewriting the exercise files during a test run. 39 | 40 | **Working around long-running track test suites** 41 | 42 | Usually as people are developing the track, they're focused on a single exercise. If running the entire track test suite against all of the exercises takes a long time, it is often worth making it possible to verify just one exercise at a time. 43 | 44 | **Example build file** 45 | 46 | The PHP track has created a [Makefile][make]. The Ruby track uses Rake, which is a tool written in Ruby, allowing the track maintainers to write custom code in the language of the track to customize the build with a [Rakefile][rake]. 47 | 48 | [make]: https://github.com/exercism/xphp/blob/master/Makefile 49 | [rake]: https://github.com/exercism/xruby/blob/master/Rakefile 50 | -------------------------------------------------------------------------------- /maintaining-a-track/README.md: -------------------------------------------------------------------------------- 1 | # Maintaining an Exercism Language Track 2 | 3 | * [Philosophy](#philosophy) 4 | 5 | * [Be Kind](#be-kind) 6 | * [Be Responsive](#be-responsive) 7 | * [Empower New Contributors](#empower-new-contributors) 8 | * [Recognize Contributions](#recognize-contributions) 9 | * [Praise in Public, Reprimand in Private](#praise-in-public-reprimand-in-private) 10 | * [Improve the Learning Experience](#improve-the-learning-experience) 11 | * [Collaborate](#collaborate) 12 | 13 | * [Day-to-Day Tactics](#day-to-day-tactics) 14 | 15 | * [Watch Key Repositories](#watch-key-repositories) 16 | * [Perform Common Tasks](#perform-common-tasks) 17 | 18 | ## Philosophy 19 | 20 | ### Be Kind 21 | 22 | First and foremost, strive always to be kind, humble and show gratitude for the work being contributed. 23 | 24 | **_Kind_ is not the same thing as _nice_.** Being kind does not mean being a pushover. 25 | Doing the right thing is not always the thing that pleases the most people. 26 | 27 | ### Be Responsive 28 | 29 | Even if you do not have an answer immediately, respond quickly. This lets the person on the other end know that they've been heard. If it takes a long time to figure out what to do, be honest about what's going on. 30 | 31 | When responding to someone, `@`-mention them. This will ensure that they'll get a notification, even if they're not watching the issue or pull request. 32 | 33 | ### Empower New Contributors 34 | 35 | As a maintainer, your most important task is to make it as easy as possible for people to successfully contribute. The exact details will vary, but often this means things like: 36 | 37 | - documenting or scripting the necessary steps to get started with the codebase 38 | - helping people understand how to use the tools successfully (including git and GitHub) 39 | - writing detailed issues about work that needs to be done so that someone without knowledge of the project can easily find something to work on 40 | - improving the tooling to reduce friction 41 | - answering questions 42 | - reviewing pull requests 43 | 44 | ### Recognize Contributions 45 | 46 | Don't just merge a PR—thank contributors for their contributions. 47 | 48 | Any contribution that helps is great, it doesn't have to be a great contribution. Let contributors know that you really value their work, no matter how small the contribution is. 49 | 50 | If someone does great work consistently over time, invite them to become maintainers. 51 | 52 | ### Praise in Public, Reprimand in Private 53 | 54 | If there is a contributor or commenter that is not behaving as we would like then it should be handled outside of GitHub if possible. 55 | 56 | ### Improve the Learning Experience 57 | 58 | The exercises often start out as an experiment. As people do the exercises we learn a lot about what's interesting, tough, boring, challenging, fun, tricky, confusing, or useful. 59 | 60 | Over time we try to: 61 | 62 | - improve the problem descriptions in [exercism/problem-specifications](https://github.com/exercism/problem-specifications) 63 | - add missing edge cases in the test suites 64 | - reorder tests to allow a more incremental approach to solving the problem 65 | - improve the test suites to avoid pushing people towards specific solutions 66 | - reorder exercises to provide a gentler learning curve on the site 67 | - deprecate exercises that don't provide enough value 68 | 69 | ### Collaborate 70 | 71 | Maintaining a track is so much more fun and interesting when there are several people actively involved in the process. 72 | 73 | Even with full push access, **create pull requests**. This notifies the other maintainers about the change. 74 | As a general rule, ensure a fellow maintainer reviews your pull request, unless it is utterly trivial. 75 | 76 | When you start working on an issue, claim it either by assigning it to yourself or by adding a comment that you're taking it. 77 | This avoids having several people do the same work by accident. 78 | 79 | If you have a big list of similar, related things, consider [generating individual issues](https://github.com/exercism/docs/issues/10) for each one so that people can claim individual tasks easily. 80 | 81 | ## Day-to-Day Tactics 82 | 83 | ### Watch Key Repositories 84 | 85 | This will notify you of all new issues, pull requests, and comments. 86 | 87 | In addition to the language track repository itself, you may also want to watch: 88 | 89 | - the [exercism/problem-specifications](http://github.com/exercism/problem-specifications) repository which contains all of the exercise descriptions and metadata. Many discussions about improvements to the exercises happen here. 90 | - the [exercism/exercism](https://github.com/exercism/exercism/issues) repository where a lot of high-level discussions about Exercism itself happen (roadmap, direction, ideas, conundrums). 91 | 92 | ### Perform Common Tasks 93 | 94 | - [Triage issues](/you-can-help/triage-issues.md) 95 | - [Review and merge pull requests](/you-can-help/review-pull-requests.md) 96 | - [Add and improve language-specific documentation](/language-tracks/documentation/for-consumers.md) 97 | - Discuss improvements in the exercises 98 | - [Implement](/you-can-help/make-up-new-exercises.md) or [port](/you-can-help/implement-an-exercise-from-specification.md) new exercises 99 | - Improve the development tooling (e.g. implementing continuous integration) 100 | - Recognize helpful contributions and [invite new maintainers](/maintaining-a-track/inviting-new-maintainers.md) 101 | -------------------------------------------------------------------------------- /maintaining-a-track/bootstrap-new-track.md: -------------------------------------------------------------------------------- 1 | # How to bootstrap a new track 2 | 3 | **Only owners of the organization can create new repositories.** 4 | 5 | ## One-time setup 6 | 7 | Run this setup the first time you are bootstrapping a new track. 8 | 9 | 1. Install [hub][]. 10 | 2. Clone the [request-new-language-track][] repository. 11 | 3. Clone the [tools][] repository. 12 | 4. Follow the instructions in the [tools README][clone-tracks] to clone all the existing tracks. 13 | 5. Create a [saved reply][saved-replies] with the following checklist, this is the new track checklist: 14 | 15 | ```markdown 16 | - [ ] Run bootstrap script 17 | `TRACK_ID= LANGUAGE= bin/bootstrap` 18 | - [ ] Turn on [Travis CI][travis] 19 | - [ ] If Windows-specific language, turn on [AppVeyor][appveyor] 20 | - [ ] If Mac-specific language, turn on [Circle CI][circle] 21 | Add it as a Linux project, then switch it to OS X in _Project Settings -> Build Environment_ 22 | - [ ] Add as a submodule to [trackler][] 23 | `TRACK_ID=; git submodule add https://github.com/exercism/$TRACK_ID tracks/$TRACK_ID` 24 | - [ ] Create [new team][new-team] for language 25 | - [ ] Add bootstrapped repository to team **with write access** 26 | - [ ] Invite maintainer to team 27 | 28 | [travis]: https://travis-ci.org/profile/exercism 29 | [appveyor]: https://ci.appveyor.com/projects/new 30 | [circle]: https://circleci.com/gh/organizations/exercism/settings#projects 31 | [trackler]: https://github.com/exercism/trackler/tree/master/tracks 32 | [new-team]: https://github.com/orgs/exercism/new-team 33 | ``` 34 | 35 | ## Bootstrap a Track 36 | 37 | Follow these steps to bootstrap a new track for a maintaner to start working on. 38 | 39 | 1. Add the "new track" label. 40 | 2. Confirm maintainer 41 | - If the requestor is volunteering, that's fine. 42 | - If the requestor is volunteering someone else for the job, confirm with that person. 43 | - If there is no maintainer, label with "needs maintainer" 44 | 3. Once a maintainer is confirmed, add the "new track" checklist as a reply. 45 | 4. Once the checklist is complete, let the requestor/maintainer know that the repo is ready for them, 46 | and point them to the launch checklist issue. 47 | 48 | [saved-replies]: https://github.com/blog/2135-saved-replies 49 | [request-new-language-track]: https://github.com/exercism/request-new-language-track 50 | [tools]: https://github.com/exercism/tools 51 | [clone-tracks]: https://github.com/exercism/tools#scripts 52 | [hub]: http://github.com/github/hub 53 | -------------------------------------------------------------------------------- /maintaining-a-track/inviting-new-maintainers.md: -------------------------------------------------------------------------------- 1 | The maintainers of a track should feel free to extend invitations to contributors asking them to join the team. 2 | 3 | You may invite new maintainers using whatever medium feels most appropriate, including but not limited to email or Gitter. 4 | 5 | In general, we would like to keep these invitations short, to make it clear that we are not asking for a huge and/or overwhelming commitment. 6 | 7 | General topics that we feel are good to touch on in the invitation: 8 | 9 | * **Thank you** for your past contributions. Be specific on points that we like, for positive reinforcement. 10 | * https://github.com/exercism/docs/tree/master/maintaining-a-track 11 | * **No pressure** regarding how much to commit to (you can commit to as much or as little as you like!), or even to say yes at all! Either way, you are still welcome to contribute as you already have been! 12 | 13 | If they agree to become maintainers, email [@kytrinyx](https://github.com/kytrinyx) and she'll add them to the correct team. 14 | 15 | We're talking about adding some sort of bot that will let maintainers invite new maintainers in their track, but we haven't gotten that far. 16 | -------------------------------------------------------------------------------- /maintaining-a-track/maintainer-configuration.md: -------------------------------------------------------------------------------- 1 | # Maintainer Configuration 2 | 3 | Each maintainer should be listed in the `config/maintainers.json` file. 4 | 5 | This file is used for two purposes: 6 | 7 | 1. to update the maintainer team for the track repository using a bot 8 | 2. to (optionally) display maintainers on the website 9 | 10 | ## Maintainer Sync Bot 11 | 12 | TODO: the bot is written, but not yet deployed/installed. Document this when the bot is turned on. 13 | 14 | ## Featuring Maintainers on Website 15 | 16 | We feature the maintainers of each track on the website. Ideally, the maintainer bio will be tailored to the track, giving a friendly view into each maintainer's background and interest in the language, and even (perhaps) what they enjoy most about maintaining the track, or what type of things they tend to focus on. 17 | 18 | The bio should be about 40 words long. 19 | 20 | The main reasons for including these are to: 21 | 22 | * provide a stronger basis for empathy with maintainers 23 | * give well-deserved recognition 24 | * plant a seed in people's minds that Exercism tracks are maintained by people like me... I could do that! 25 | 26 | Being featured on the Exercism website is entirely optional, and we're generating all the data with `show_on_website=false` so that if you don't want to bother, you don't have to change anything. 27 | 28 | ## Alumnus 29 | 30 | When you decide to move on, submit and merge a PR that sets the `alumnus` key 31 | for your maintainer entry to one of the following strings: 32 | `alumnum`, `alumnus` or `alumna`. 33 | This is the string that will appear with your bio on the website. These terms 34 | have been chosen to enable you to choose the one you feel most appropriate for 35 | your gender. 36 | 37 | ## JSON Format 38 | 39 | The format for each entry is: 40 | 41 | ``` 42 | { 43 | "github_username": "iHiD", 44 | "show_on_website": false, 45 | "alumnus": null, 46 | "name": "Jeremy Walker", 47 | "bio": "A friendly, detailed description of your background/interest in the language, to go on the Exercism track page.", 48 | "link_text": "My Website", 49 | "link_url": "http://ihid.co.uk", 50 | "avatar_url": "http://example.com/iHiD.png", 51 | } 52 | ``` 53 | 54 | The only required field is `github_username`. 55 | 56 | If `show_on_website` is missing or `false` then the maintainer will not be featured on the Exercism.io website. 57 | - `show_on_website` 58 | 59 | Optional fields: 60 | 61 | - `alumnus`: defaults to null if absent. 62 | - `avatar_url`: defaults to your GitHub avatar if `null` or absent. 63 | - `name`: defaults to whatever your public display name on GitHub is. If you have not filled in this field, and there is no name defined on your GitHub profile, we will use your GitHub username as your display name. 64 | - `bio`: if null or absent, it defaults to your public GitHub bio (note that I don't think this is a great default, I would much rather have a bio that is specific to the track). If this is an empty string we will not show a bio at all. 65 | - `link_text`: no default. If absent we will use the `link_url` as the anchor. 66 | - `link_url`: no default. If absent we will link to your GitHub profile. 67 | -------------------------------------------------------------------------------- /maintaining-a-track/regenerating-exercise-readmes.md: -------------------------------------------------------------------------------- 1 | # Regenerating Exercise READMEs 2 | 3 | In order to give maintainers more control over the contents and formatting of each exercise README, it is generated from a template that the maintainers control. However, in order to avoid having to reinvent the universe from scratch when porting a new exercise from a shared specification, this README can be generated based on the specification description and other metadata. 4 | 5 | The command to regenerate all the READMEs is: 6 | 7 | ``` 8 | configlet generate . 9 | ``` 10 | 11 | See the [exercise READMEs][readmes] documentation for more details. 12 | 13 | [readmes]: /language-tracks/exercises/anatomy/readmes.md 14 | -------------------------------------------------------------------------------- /maintaining-a-track/starting-new-track.md: -------------------------------------------------------------------------------- 1 | # Starting a New Language Track 2 | 3 | You want to start a new language track for `exercism`, that's great! There's a few things to check first: 4 | 5 | **Does Exercism already support the language?** 6 | 7 | Check [this list][trackler-tracks], which contains both the active and inactive tracks on the site. 8 | 9 | If you find the language, follow the links from that list to view the repository. 10 | The `config.json` file has an `active` key, which will be true or false. 11 | If the track is active, then refer to the docs on [contributing to a language track][contributing-to-track]. 12 | If the track is innactive, do something else. 13 | 14 | **Has someone else asked for it?** 15 | 16 | Do a search in the [resquest-new-language-track][request-language-track-repo] repository for the name of the language. Remember to check both open and closed issues. 17 | A closed issue will have the reasoning why the track was closed without being added. 18 | If the issue is open, reply to it explaining that you want to maintain that track. 19 | 20 | [new-issue]: https://github.com/exercism/request-new-language-track/issues/new 21 | [request-language-track-repo]: https://github.com/exercism/request-new-language-track 22 | [trackler-tracks]: https://github.com/exercism/trackler/tree/master/tracks 23 | [contributing-to-track]:https://github.com/exercism/docs/tree/master/contributing-to-language-tracks 24 | 25 | **No one has asked for the track I want yet.** 26 | 27 | If you're interested in adding problems for a language that we don't yet have, 28 | open an issue in the https://github.com/exercism/request-new-language-track repository. 29 | Follow the issue template to get started. 30 | 31 | ## Beta-Testing a Language Track 32 | 33 | --- 34 | For a track that is set as `"active": false` in the `config.json`, `exercism fetch` 35 | will not automatically pull down problems. You can still test the language by 36 | fetching problems directly, e.g.: 37 | 38 | ```shell 39 | exercism fetch cpp bob 40 | ``` 41 | 42 | This will allow you to do some dry-run tests of fetching exercises, 43 | double checking the instructions for each problem and submitting the 44 | problem solution for peer review. 45 | 46 | It is recommended that you configure a [Travis continuous integration build](http://travis-ci.org) 47 | with your language track to verify that your example problem solutions 48 | satisfy the tests provided for each problem. 49 | 50 | You can include advice and helpful links for your language track in the 51 | `SETUP.md` file. 52 | 53 | ## How to improve the process for the next new maintainer 54 | 55 | It's crucial that we improve the documentation and instructions for launching a track. 56 | The best people to discover issues with our current process are new maintainers, launching a track for the first time. 57 | Unfortunately, that's the worst possible time for them to fix the documentation, because they've got the least amount of knowledge about how Exercism is put together. 58 | 59 | The files in [resquest-new-language-track][request-language-track-repo] repository serve as a template for a new track. 60 | Some files get edited and added to the track, others are used to [create new issues in the track][issue-templates], but are not added to the new repository. 61 | If new maintainers have questions, look at these files, as they're the most likely culprit with confusing or missing information. 62 | 63 | When that happens, we should tweak the documentation for clarity. 64 | Open a new pull request to the [resquest-new-language-track][request-language-track-repo] repository, not their language respository. Be sure to tag the maintainer to review it so they can confirm it would eliminate their question or confusion. 65 | If it's still confusing, they'll know, and figuring out how to explain it will help us fix it. 66 | 67 | In some cases, we might discover that we're missing high-level documentation that should live here in the [docs][] repo. 68 | In that case case we should open an issue or pull request [here][docs], proposing the new documentation. Tag the new 69 | maintainer here, as well, to get their input on the new docs. 70 | 71 | ## How to make maintaning your new track fun 72 | 73 | Ideally a track will have several maintainers. This makes the discussions more lively and interesting, and it makes the track more resilient to illnesses, job changes, new babies, and all the other excitement that real lifeTM brings. 74 | We encourage you to recruit others to help you maintan your track. More hands can help make the work more lively and spread the workload. 75 | 76 | ### More Lively 77 | 78 | We've noticed that as soon as there are at least two people maintaining the same track we get rich discussions about quality and idioms. 79 | There's a lot more activity, and as a result it's a lot more fun. 80 | 81 | ### Helps to Spread the Workload 82 | 83 | We don't want to burn people out. 84 | It's really nice to be able to go on vacation or get busy at work without worrying too much about a growing backlog of unanswered issues and unreviewed and unmerged pull requests. 85 | 86 | ### Caveat 87 | 88 | Something to keep in mind while working with more people is it the chance for diffusion of responsibility. 89 | If you're unfamilliar with the term, it generally refers to the phenomena where a single person is less likely to take responsibility for an action or inaction if there are others present. 90 | You can work with your other maintainers to avoid this by clearly communicating and dividing tasks. 91 | 92 | [checklist]: https://github.com/exercism/request-new-language-track/blob/master/CHECKLIST.md 93 | [docs]: https://github.com/exercism/docs 94 | [issue-templates]: https://github.com/exercism/request-new-language-track/blob/master/bin/bootstrap#L67-L73 95 | 96 | ## How to bootstrap a new track 97 | 98 | If you're an organization owner looking for the checklist and guide to boostrap a new track, please refer to the [bootstrapping a new track documentation][bootstrap-track]. 99 | 100 | [bootstrap-track]:https://github.com/exercism/docs/blob/master/maintaining-a-track/bootstrap-new-track.md 101 | -------------------------------------------------------------------------------- /you-can-help/implement-an-exercise-from-specification.md: -------------------------------------------------------------------------------- 1 | # Porting an Exercise to Another Language Track 2 | 3 | [problem-specifications]: http://github.com/exercism/problem-specifications/tree/master/exercises 4 | [support-chat]: https://gitter.im/exercism/support 5 | [configlet]: https://github.com/exercism/configlet#configlet 6 | [exercises]: /language-tracks/configuration/exercises.md 7 | 8 | Exercism has a lot of exercises in a lot of languages. 9 | 10 | There is a common pool of problem definitions, which can be implemented in any 11 | of the language tracks. 12 | 13 | The language-agnostic definition lives in the [problem-specifications][] repository, within 14 | the `exercises/` directory: 15 | 16 | /exercises/$SLUG/ 17 | ├── canonical-data.json (OPTIONAL) 18 | ├── description.md 19 | └── metadata.yml 20 | 21 | The shared data will always have a `description.md` file which contains the basic 22 | problem specification, and which later gets used to generate the README for the 23 | exercises. 24 | 25 | The `metadata.yml` contains a summary (or "blurb") of the exercise, as well as 26 | attribution and some other handy things that get used in various places. 27 | 28 | For some exercises we have defined a `canonical-data.json` file. If this exists 29 | then you won't need to go look at implementations in other languages. This will 30 | contain the implementation notes and test inputs and outputs that you'll need 31 | to create a test suite in your target language. 32 | 33 | ## Finding an Exercise to Port 34 | 35 | Navigate to the language track on Exercism via the [https://tracks.exercism.io](https://tracks.exercism.io) page. 36 | 37 | Select the language of interest. You shall see a table that has multiple tabs. Click the tab labelled **Unimplemented**. 38 | 39 | This is a full list of every exercise that exists, but has not yet been implemented 40 | in that language track. 41 | 42 | For every exercise it will link to: 43 | 44 | - The generic README. 45 | - The canonical data (if it exists). 46 | - All the individual language implementations. 47 | 48 | ## Implementing the Exercise 49 | 50 | You'll need to find the `slug` for the exercise. That's the URL-friendly identifier 51 | for an exercise that is used throughout all of Exercism. 52 | 53 | **The name of the exercise directory in the [problem-specifications][] repository is the slug.** 54 | 55 | Create a new directory named after the slug in the `exercises` directory of the language 56 | track repository. 57 | 58 | The exercise should consist of, at minimum: 59 | 60 | * A test suite. 61 | * A reference solution that passes the tests. 62 | 63 | Each language track might have additional requirements; check the README in 64 | the repository for the track. 65 | 66 | ### The Test Suite 67 | 68 | Look at the other exercises in the track to get an idea of: 69 | 70 | * The conventions used. 71 | * How to name the test file. 72 | 73 | ### The Reference Solution 74 | 75 | The reference solution is named something with `example` or `Example` in the path. 76 | 77 | Again, check the other exercises to see what the naming pattern is. 78 | 79 | The solution does not need to be particularly great code, it is only used to verify 80 | that the exercise is coherent. 81 | 82 | ### Configuring the Exercise 83 | 84 | Add a new entry in the `exercises` key in the `config.json` file in the root of the repository. 85 | 86 | See the [exercise configuration document][exercises] for a detailed description of what you need to add to this entry. 87 | 88 | We have a tool, [configlet][configlet] that will help make sure that everything is configured right. 89 | Download that and run it against the track repository. 90 | 91 | ### Submitting a Pull Request 92 | 93 | Rebase against the most recent upstream master, and submit a pull request. 94 | 95 | If you have questions your best bet is the [support chat][support-chat]. Once you 96 | figure it out, if you could help improve this documentation, that would be great! 97 | 98 | ### Providing Feedback on the Site for an Exercise You Implemented 99 | 100 | Once you've created an exercise, you'll probably want to provide feedback to people who 101 | submit solutions to it. By default you only get access to exercises you've submitted 102 | a solution for. 103 | 104 | You can fetch the problem using the CLI: 105 | 106 | ```bash 107 | $ exercism fetch 108 | ``` 109 | 110 | Go ahead and submit the reference solution that you wrote when creating the problem. 111 | Remember to archive it if you don't want other people to comment on it. 112 | -------------------------------------------------------------------------------- /you-can-help/improve-exercise-metadata.md: -------------------------------------------------------------------------------- 1 | # Improving Consistency Across Tracks 2 | 3 | [blazon]: https://github.com/exercism/blazon 4 | [problem-specifications]: https://github.com/exercism/problem-specifications/tree/master/exercises 5 | 6 | ## Canonical Data 7 | 8 | Each exercise has a generic, language-agnostic problem description, which 9 | can then be implemented in any of the Exercism language tracks. 10 | 11 | A great test suite will help people solve the problem gradually. 12 | 13 | We want to avoid 14 | 15 | * too much redundancy 16 | * steps that are too big 17 | 18 | Once we've found a good set of tests, we formalize the inputs and outputs and 19 | store it in a file called `canonical-data.json` alongside the language-agnostic 20 | problem description in the [problem-specifications][] repository. 21 | 22 | This makes it easier to port the exercises to new language tracks, as well as 23 | propagate changes to the exercises that have already been implemented in 24 | many tracks. 25 | 26 | ## Extracting Canonical Test Data 27 | 28 | Each of the exercises in the [common pool of exercises][problem-specifications-exercises] can have a 29 | `canonical-data.json` file alongside the other files defining the exercise: 30 | 31 | ``` 32 | exercises// 33 | ├── canonical-data.json 34 | ├── description.md 35 | └── metadata.yml 36 | ``` 37 | 38 | This JSON file should contain the generic (i.e. language independent) test data for that exercise. 39 | 40 | There are [open issues][canonical-data-issues] for all of the exercises that are missing canonical data. 41 | The open issue has a link to a page that contains an up-to-date list of all the language tracks that 42 | have implemented the exercise, as well as links to view the implementations. 43 | 44 | Open each implementation in a separate browser tab. Navigate to the test files and read through the tests. 45 | Look for test cases that all/many of the languages have in common and identify outliers that only appear in one or two languages. 46 | 47 | Based on your findings, decide on a sensible set of test cases. 48 | 49 | Here are some considerations that may help: 50 | 51 | * Try to stick to test cases that already occur in many languages so it is feasible for the track maintainers to adapt to the canonical set. 52 | * All tests should be essential to the problem. Ensure people can get the first test passing easily. Then each following test should ideally add a little functionality. People should be able to solve the problem a little at a time. Avoid test cases that don't introduce any new aspect and would already pass anyway. 53 | * The test cases should not require people to follow one very specific way to solve the problem, e.g. the tests should avoid checking for helper functions that might not be present in other implementations. 54 | * Performance tests should not be included in the canonical test data. 55 | 56 | Once you've decided on a set of test cases, create the `canonical-data.json` file following the guidelines in [problem-specifications's README][data-format-docs]. 57 | 58 | If you are unsure about any of the considerations make a pull request with an initial proposal and ask the community for help. 59 | 60 | ## Using Canonical Data to Implement Exercises 61 | 62 | When porting an exercise to a language track, the canonical data file 63 | makes it easy to select and implement test cases. 64 | 65 | If the track uses test generators (check the README), then you may want to 66 | write a generator rather than hand-code the test suite. 67 | 68 | Some things vary from language to language, so don't feel constrained 69 | to implementing exactly what is in the `canonical-data.json` file. 70 | 71 | ## Evolving Exercises 72 | 73 | Over time we find that the problem definitions can be improved in various ways. 74 | 75 | When they do, we need to notify all of the tracks that have an implementation 76 | of that problem so that they can update it. 77 | 78 | We've built some tooling for this, [blazon][blazon], to make it easier to manage. 79 | 80 | The process goes like this: 81 | 82 | **Open an issue** in the problem-specifications repository describing the problem, the fix, 83 | and the reasoning behind it. Link to any relevant discussions. This is the _parent 84 | issue_. 85 | 86 | In the comment of the issue, **draft the body of an issue** which will be 87 | submitted to each of the language tracks that have implemented this problem. 88 | 89 | This should contain: 90 | 91 | - a description of the edge case or change 92 | - explicit instructions about what change to make 93 | - a note saying "if this isn't relevant in this language track, close the 94 | issue" 95 | - a link to the canonical data (if it exists) 96 | - a link to the parent issue. 97 | 98 | Linking back to the parent issue is important for two reasons: 99 | 100 | 1. It provides context. If someone wants to know more about the issue, 101 | they can follow links to read the history. 102 | 2. It will show a _living TODO list_. The parent issue will have a list 103 | of links to the open issues, showing whether the issue is open or 104 | closed. Once all of the child issues are closed, then we can 105 | close the parent issue. 106 | 107 | It's worth drafting this in a comment because other people will often weigh in 108 | to help make it as clear as possible, or add any missing context, and it's 109 | easier to fix this _before_ it get submitted to a bajillion different repos. 110 | 111 | **Create a text file** containing the issue template that you drafted. 112 | 113 | The first line of the file will be used as the issue title. Make it 114 | descriptive. It should contain the slug of the relevant exercise. 115 | 116 | **Download [blazon][blazon]** and use it to submit the issue. 117 | 118 | $ blazon -exercise= -file= 119 | 120 | 121 | [problem-specifications-exercises]: https://github.com/exercism/problem-specifications/tree/master/exercises 122 | [canonical-data-issues]: https://github.com/exercism/problem-specifications/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22cross-track%20consistency%22%20canonical-data.json 123 | [data-format-docs]: https://github.com/exercism/problem-specifications#test-data-format-canonical-datajson 124 | -------------------------------------------------------------------------------- /you-can-help/make-up-new-exercises.md: -------------------------------------------------------------------------------- 1 | # Implementing a Completely New Exercise 2 | 3 | ## Generic or Custom 4 | 5 | Before adding a new exercise, consider whether this is an exercise that is relevant to just one language, or could be reused or adapted across multiple Exercism language tracks. 6 | 7 | If your exercises is relevant to several tracks, then you will create a _generic_ problem specification in a shared repository. If your exercise is relevant only to a specific programming language, then you will create a _custom_ specification within the language track repository. 8 | 9 | ## Problem Specification 10 | 11 | Whether you are creating a generic or a custom exercise, the basic idea is the same. Some details will differ, and these are described in detail below. 12 | 13 | * First, choose a name for your exercise. The name must be unique. Verify the list of [generic problem specifications][spec-exercises], as well as the language track in question (navigate to the `exercises` directory in the repository). 14 | * Derive the _slug_ of the exercise from the name by making the name all lowercase and separating words using hyphens. 15 | * Write a _blurb_, which is a one-sentence summary of the problem to be solved. 16 | * Write a more detailed _description_ of the problem to be solved. 17 | * Reference the _source_ of inspiration for the exercise. 18 | 19 | The basic problem specification consists of two files. Where these files live will depend on whether you're creating a generic or custom exercise. 20 | 21 | The `description.md` contains a general description of the problem to be solved described in plain text, without a title/header. It will likely be two or three paragraphs. Try to make the description independent of any programming language. Think about whether the description would work for someone who wanted to solve this problem on the back of a napkin using pen and paper. 22 | 23 | The `metadata.yml` contains the blurb and source. It has the following structure: 24 | 25 | ``` 26 | --- 27 | blurb: "A one-sentence summary of the problem to be solved." 28 | title: "An *optional* field containing the name of this exercise if the default algorithm does not correctly convert the slug to the correct name. The default algorithm capitalises the first letter of each hyphen-separated word. If the default algorithm correctly converts the slug, this field can/should be omitted." 29 | source: "A textual description of where this was found, or what inspired it." 30 | source_url: "http://example.com/reference" 31 | ``` 32 | 33 | ### Generic Problem Specifications 34 | 35 | Generic problem specifications live in the [exercism/problem-specifications][problem-specifications] repository, with the [exercises directory][spec-exercises]. 36 | 37 | A generic specification consists of three files in a directory named after the slug (`hello-world`, in this case): 38 | 39 | ``` 40 | exercises/ 41 | └── hello-world 42 | ├── canonical-data.json 43 | ├── description.md 44 | └── metadata.yml 45 | ``` 46 | 47 | The `canonical-data.json` file contains a set of sample test inputs and outputs that make up a reasonable test suite. Since you are creating a new exercise, you might want to implement a test suite for the track in question and then create the canonical data, based on your discoveries and insights from having written an actual test suite. 48 | 49 | Some general guidelines: 50 | 51 | * All tests should be essential to the problem. 52 | * Ensure people can get the first test passing easily. Then each following test should ideally add a little functionality. People should be able to solve the problem a little at a time. 53 | * Avoid test cases that don't introduce any new aspect and would already pass anyway. 54 | * The test cases should not require people to follow one very specific way to solve the problem, e.g. the tests should avoid checking for helper functions that might not be present in other implementations. 55 | * Performance tests should not be included in the canonical test data. 56 | 57 | The expected format for the `canonical-data.json` file can be found in the [canonical schema](https://github.com/exercism/problem-specifications/blob/master/canonical-schema.json). 58 | 59 | Once your pull request to the problem-specifications repository is merged, you can follow the directions for [implementing an exercise from specification][porting-an-exercise]. 60 | 61 | ### Custom Problem Specifications 62 | 63 | Within the language track repository, the metadata files need to go in a `.meta` directory within the exercise directory when you submit your implementation of the exercise. 64 | 65 | ``` 66 | exercises/ 67 | └── hello-world 68 | └── .meta 69 | ├── description.md 70 | └── metadata.yml 71 | ``` 72 | 73 | Once you've defined these, you can submit them along with your pull request that [implements the exercise][porting-an-exercise]. 74 | 75 | [problem-specifications]: https://github.com/exercism/problem-specifications 76 | [spec-exercises]: https://github.com/exercism/problem-specifications/tree/master/exercises 77 | [porting-an-exercise]: /you-can-help/implement-an-exercise-from-specification.md 78 | -------------------------------------------------------------------------------- /you-can-help/review-pull-requests.md: -------------------------------------------------------------------------------- 1 | # Reviewing a Pull Request 2 | 3 | This guide is about reviewing pull requests on Exercism language tracks. 4 | 5 | ## Philosophy 6 | 7 | * **Respond Kindly** We want every contributor to be glad they are here, even if we don't ultimately merge their pull request. 8 | * **Respond Quickly** Promptness encourages frequent, high-quality contributions from community members and other maintainers. 9 | * **Resolve Quickly** A pull request should either be actively in-progress, or it should be merged or closed. 10 | 11 | Closing pull requests kindly is not easy. Two great articles about this are: 12 | 13 | * [Kindly Closing Pull Requests](https://github.com/blog/2124-kindly-closing-pull-requests) by Mike McQuaid 14 | * [The Art of Closing](https://blog.jessfraz.com/post/the-art-of-closing/) by Jessie Frazelle 15 | 16 | ## Reviewing an Exercism Exercise 17 | 18 | When reviewing a pull request, always remember the past. That is, remember that numerous users have already submitted an exercise and any significant change to an exercise invalidates their submissions to some extent. 19 | 20 | That said, we should not be afraid to change things for the better. 21 | 22 | If the tests do change significantly enough to break existing solutions, it's worth calling it out so that we can discuss whether or not the change is worth it in this particular case. 23 | 24 | ### Consider the Structural Requirements 25 | 26 | We have a tool, [`configlet`](https://github.com/exercism/configlet#configlet), which does track-level linting. This runs on Travis CI when a pull request is submitted. 27 | 28 | The tool checks the following (so you don't have to): 29 | 30 | - Is the `config.json` file syntactically correct? 31 | - Does the `config.json` list the correct exercises? 32 | - Has every exercise listed been implemented? 33 | - Has every implemented exercise been added to the config? 34 | - Have any exercises been implemented that shouldn't have been? E.g. exercises that are inappropriate or uninteresting in the language. 35 | - Is the example solution named with `/example/i` in the path? If not that file will be served when people fetch the exercise. 36 | 37 | You can also [download it](https://github.com/exercism/configlet/releases/latest) and run it locally. 38 | 39 | Things that the tool does not yet do, and which should be checked: 40 | 41 | - Is the test file named correctly, per the guidelines in the language track? (TODO: add to `configlet`) 42 | - Does the directory name of the exercise match that of [an existing, known exercism exercise slug](https://github.com/exercism/problem-specifications/tree/master/exercises)? 43 | 44 | If there is no automated checking, then you should also verify: 45 | 46 | - Do the tests pass against the example solution? 47 | 48 | ### Consider Future Maintainers 49 | 50 | - Does the commit message contain the [exercise slug](https://github.com/exercism/problem-specifications/blob/master/CONTRIBUTING.md#updating-a-generic-problem-description)? 51 | - Does the commit message explain _why_ the change was made? 52 | 53 | ### Consider the User Experience 54 | 55 | - Is the exercise listed too early in the list? Too late? 56 | - Is the exercise too similar to the ones just before or after it? 57 | - Are the tests forcing people towards a particular implementation? 58 | - Are the tests ordered so that they encourage incremental changes? 59 | - Do the test names help the user understand the _why_ of the requirement? 60 | - Will the test failures make sense to the person trying to solve the problem? 61 | - Does the exercise pull in unnecessary dependencies? 62 | - Have all but the first test been skipped? (Only for tracks that use `pending` or `skip` or `ignore` directives) 63 | - If the exercise introduced difficult language features, is there a `hints.md` file that points to some good documentation about it? 64 | - Do the tests use the data from the [`canonical-data.json`](https://github.com/exercism/problem-specifications#test-data-format-canonical-datajson) file (if it exists)? Are any of the deviations from `canonical-data.json` generally useful to other language tracks? _If so, consider submitting them back to the problem-specifications repository._ 65 | 66 | There is usually no right answer, and sometimes the best answer is "I don't know, we'll see." 67 | If it seems good enough we can merge it. It can always be improved later. 68 | 69 | ### Encourage Best Practices 70 | 71 | Consider the tests carefully. They are the public-facing product. These should follow language-idioms and make good use of the standard library. 72 | 73 | When reviewing pull requests, try to coach the contributor towards a better solution. Try not to prescribe changes outright. Ask questions, be curious, and remember that their perspective might be just as valid as yours. 74 | 75 | Exercism should generally adhere to the idioms of a language. However, that should not stand in the way of implementing a great exercise. 76 | 77 | The example solution is not public-facing, and as long as it passes the tests, we can let it in. 78 | 79 | ## Reviewing Changes to Track Tooling 80 | 81 | Changes to tooling are not user-facing, but anything that is weird or complicated will make it harder to contribute to the track. 82 | 83 | --------- 84 | 85 | Inspired by the ["reviewing a pull request"](https://github.com/jekyll/jekyll/blob/master/docs/_docs/maintaining/reviewing-a-pull-request.md) documentation in the Jekyll project. 86 | -------------------------------------------------------------------------------- /you-can-help/triage-issues.md: -------------------------------------------------------------------------------- 1 | # Triaging Issues in an Exercism Language Track 2 | 3 | Issues need to be unambiguous and actionable. If it's hard to figure out what 4 | an issue is about, or what needs to be done, then the issue probably won't get 5 | fixed. 6 | 7 | ## Making Issues Great 8 | 9 | The goal of triaging issues is to make sure that each issue is actionable. 10 | 11 | A great issue has enough context that it could be tackled by someone who has never contributed 12 | to Exercism before. 13 | 14 | When reading an issue you should be able to answer questions like... 15 | 16 | * What is the problem? 17 | * Why is this a problem? 18 | * Who might run into it? Everyone? Or is it an edge case? 19 | * What needs to be done? How will we know that the issue can be closed? 20 | Is there something we need to figure out or decide before it can be fixed? 21 | * Where in the code will the fix go? This might be obvious, but it might not be. If we can point 22 | to the right directory or file, that helps. 23 | 24 | If the issue isn't great yet, then the best help you can provide is to ask clarifying questions to help 25 | make it great. 26 | 27 | ## Still Relevant? 28 | 29 | Along the way you might run into issues that have already been resolved (we just forgot to close it), or 30 | that just aren't relevant any more, because the world has moved on. 31 | 32 | If you see one of these, then add a comment suggesting that we close it, with a note about why it can be 33 | closed. 34 | -------------------------------------------------------------------------------- /you-can-help/update-exercise-test-suites.md: -------------------------------------------------------------------------------- 1 | # Updating an Exercise Test Suite 2 | 3 | Once you [find the correct repository](#language-track-repositories), 4 | you can [fork it](https://help.github.com/articles/fork-a-repo/) and then [clone it](https://help.github.com/articles/cloning-a-repository/). 5 | 6 | The README in each individual language track repository covers how to set 7 | up the development environment for that language. 8 | 9 | Often all you need is a running language environment along with the relevant 10 | testing library. 11 | 12 | If the test suite was generated, then editing the solution will require a 13 | couple of extra steps. This is covered in detail in a [separate section of 14 | this guide](#updating-a-generated-test-suite). 15 | 16 | The test suite is usually named with _test_ or _Test_ in the filename, though 17 | some language tracks have other conventions (e.g. _spec_ is fairly common, and 18 | sometimes it's just a matter of a different file extension). 19 | 20 | If you're unsure where to make the change, ask us, and we'll help you figure it out. 21 | 22 | Once you've updated the test suite, there are a few things you'll want to check. 23 | 24 | - Make sure the [reference solution](#reference-solution) is still passing. 25 | - If the exercise is [versioned](#exercise-versioning), and the change will 26 | mean that existing solutions on the site will not pass the new tests, then 27 | increment the version number, both in the test and in the reference solution. 28 | - Run the full, track-level test suite, if available. 29 | If the track has a way to automatically run all the tests against their 30 | reference solutions, it will be documented in the README. 31 | - Run [configlet](#track-level-linting-with-configlet), the track-level linter. 32 | 33 | You can also take a look at the `.travis.yml` file to see what the continuous 34 | integration system will do to verify the track. 35 | 36 | Take a look at our [pull request guidelines](#pull-request-guidelines). 37 | You don't need to get it perfect the first time around; we'll work with you to 38 | get the patch merged. 39 | 40 | ## Updating a Generated Test Suite 41 | 42 | Some language tracks are experimenting with generating test suites from shared 43 | test data. This is because various interesting edge cases are discovered as 44 | people discuss solutions, but these edge cases are usually then only added 45 | to a single language track. By standardising the inputs and outputs, it becomes 46 | easier to improve the exercises across all the languages. 47 | 48 | There are two possible scenarios, described below. 49 | 50 | 1. You want to change or add inputs or outputs. 51 | 1. You want to change something about the test suite itself. 52 | 53 | Once you've made the change, then follow the instructions about verifying your change 54 | and submitting a patch as described above, in the section about [updating an exercise 55 | test suite](#updating-an-exercise-test-suite). 56 | 57 | ### Changing Inputs and Outputs 58 | 59 | If you want to add a new test or change some inputs or outputs, then the change 60 | needs to be made in the [exercism/problem-specifications repository](https://github.com/exercism/problem-specifications), 61 | not directly to the test suite itself. 62 | 63 | Find the JSON file for the problem in question. For example, if you want to change 64 | the Clock problem, then look for `exercises/clock/canonical-data.json`. Each 65 | change should also bump the version of the test data. For more information, 66 | see the [test data versioning](README.md#test-data-versioning) section of the 67 | README. 68 | 69 | Submit a pull request with the change. 70 | 71 | When that pull request has been merged, then the various languages that implement that 72 | problem will need to have their test suites regenerated. Track maintainers can do this, 73 | though we're always happy if you want to submit a patch with the regenerated test suite. 74 | 75 | The instructions for regenerating a test suite should be described in the README 76 | of the language-specific repository. 77 | 78 | Follow the guidelines for setting up a development environment, verifying the change, 79 | and submitting a pull request, as described in the [main section about updating an 80 | exercise test suite](#updating-an-exercise-test-suite). 81 | 82 | ### Changing the Structure 83 | 84 | If you are not changing inputs/outputs, but rather the structure of the test suite, 85 | then that change will need to be made within the generator itself. It lives in 86 | the language-specific repository along with the exercises, and the process for 87 | regenerating the exercise should be described in the README of the repository. 88 | 89 | Follow the guidelines for setting up a development environment, verifying the change, 90 | and submitting a pull request, as described in the [main section about updating an 91 | exercise test suite](#updating-an-exercise-test-suite). 92 | --------------------------------------------------------------------------------