From be7fed796b417ed232b35f94ccb1ba88dfcdf06d Mon Sep 17 00:00:00 2001 From: BethanyG Date: Tue, 5 Oct 2021 14:41:45 -0700 Subject: [PATCH 01/31] First re-write pass of contributing docs. --- CONTRIBUTING.md | 154 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 135 insertions(+), 19 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9f0fffcdfb..14de14cce7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,22 +1,138 @@ -# Contributing Guide - -This document supplements the [Exercism contributing guide]; all contributors should read that document before proceeding. - -## Table of Contents - -- [Contributing Guide](#contributing-guide) - * [Architecture](#architecture) - * [Implementing an exercise](#implementing-an-exercise) - + [Exercise structure](#exercise-structure) - + [Generating Exercise READMEs](#generating-exercise-readmes) - - [Requirements](#requirements) - - [Generating all READMEs](#generating-all-readmes) - - [Generating a single README](#generating-a-single-readme) - + [Implementing tests](#implementing-tests) - + [Example solutions](#example-solutions) - + [config.json](#configjson) - * [Implementing Track-specific Exercises](#implementing-track-specific-exercises) - * [Pull Request Tips](#pull-request-tips) +# Contributing + +πŸ‘‹πŸ½ πŸ‘‹ Hi. Thank you so much for your interest in contributing to the Python track! **We are happy you are here.**🌟 :tada: + + +`exercsim/Python` is one of the many tracks on [exercism](https://exercism.org/). This repo holds all the instructions, tests, code, & support files for Python *exercises* currently under development or implemented & available for students. + +Exercises are grouped into **concept** exercises which teach the [Python syllabus](https://exercism.org/tracks/python/concepts), and **practice** exercises, which are unlocked by progressing in the syllabus tree. Practice exercises are open-ended, and can be used to practice concepts learned, try out new techniques, and _play_. These two exercise groupings can be found in the track [`config.json`](https://github.com/exercism/javascript/blob/main/config.json), and under the `python/exercises` directory. + + + +#### πŸ› **Did you find a bug?** + +It's not uncommon that people discover typos, confusing directions, or incorrect implementations of certain tests or code examples. Or you might have a great suggestion for a hint to aid students (πŸ’™) , see optimizations for exemplar or test code, find some missing test cases to add, or want to correct factual and/or logical errors. Or maybe you have a great idea for an exercise or feature. + +_Our track is always a work in progress!_ 🌟🌟 Please πŸ“› [Open an issue](https://github.com/exercism/python/issues/new/choose)  πŸ“› , and let us know what you've found. + + + +#### 🚧 **Did you write a patch that fixes a bug? ** + + πŸ’› πŸ’™ **We Warmly Welcome Pull Requests that are:** + +             1️⃣    Small, contained fixes for typos/grammar/punctuation/code syntax on [one] exercise, +             2️⃣     Medium changes that have been agreed/discussed via a filed issue, +             3️⃣     Contributions from our [help wanted](https://github.com/exercism/python/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) issue list, +             4️⃣     Larger (_and previously agreed-upon_) contributions from recent & regular (_within the last 6 months_) contributors. + +When in doubt, πŸ“› [Open an issue](https://github.com/exercism/python/issues/new/choose)  πŸ“›. We'll happily discuss your proposed change. 🐍 + +But let's talk before you take a whole lot of time implementing anything. + + + +#### :books: **Want to jump directly into Exercism specifications & detail? ** + +[Track Structure](https://github.com/exercism/docs/tree/main/building/tracks) **|** [Tasks](https://exercism.org/docs/building/product/tasks) **|** [Concepts](https://github.com/exercism/docs/blob/main/building/tracks/concepts.md) **|** [Concept Exercises](https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md) **|** [Practice Exercises](https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md) **|** [Presentation](https://github.com/exercism/docs/blob/main/building/tracks/presentation.md) **|** [ Style Guide for Writing](https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md) **|** [Markdown Specification](https://github.com/exercism/docs/blob/main/building/markdown/markdown.md) + + + +## The Exercism Community + + + +🌟🌟 If you have not already done so, please take a moment to read our [Code of Conduct](https://exercism.org/docs/using/legal/code-of-conduct) & [Being a Good Community Member](https://github.com/exercism/docs/tree/main/community/good-member) . It might also be helpful to take a look at [The words that we use](https://github.com/exercism/docs/blob/main/community/good-member/words.md). + + + +Some defined roles in our community: [Community Member](https://github.com/exercism/docs/tree/main/community/good-member) | [Contributors](https://github.com/exercism/docs/blob/main/community/contributors.md) |[Mentors](https://github.com/exercism/docs/tree/main/mentoring) | [Maintainers](https://github.com/exercism/docs/blob/main/community/maintainers.md) | [Admins](https://github.com/exercism/docs/blob/main/community/administrators.md) + + + +## In General + + + +- Pull requests should be focused on a single exercise, issue, or change. +- PR titles and descriptions should make clear **what** has changed and **why**. Please link πŸ”— to any related issues the PR addresses. +- πŸ“› [An issue should be opened](https://github.com/exercism/python/issues/new/choose) πŸ“› _**before**_ creating a PR that makes significant or breaking change to an existing exercise. The same holds true for changes across multiple exercises. It is best to discuss these changes with 🧰 maintainers before doing the work. +- Follow coding standards found in [PEP8](https://www.python.org/dev/peps/pep-0008/) ( ["For Humans" version here](https://pep8.org/).) We do have some more specific requirements. More on that later. +- All files should have a proper [EOL](https://en.wikipedia.org/wiki/Newline) at the end. This means one carriage return at the end of the final line of text in files. +- Watch out otherwise for trailing spaces, extra blank lines, and spaces in blank lines. ⚠️ +- The CI is going to run **a lot** of check on your PR. Pay attention to the failures, try to understand and fix them. If you need help, comment in the PR or issue. πŸ™‹πŸ½β€β™€οΈ + + + +## A Little More on Writing Style and Standards + + + +Non-code content (_exercise introductions & instructions, hints, concept write-ups, documentation etc._) should be written in [American English](https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md) . We strive to watch [the words we use](https://github.com/exercism/docs/blob/main/community/good-member/words.md). + +When a usage is contested or ambiguous, we default to what is best understood by our international community of learners, even if it "sounds a little weird" to a "native" American English speaker. + +Our documents use [Markdown](https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf) , with certain [alterations](https://github.com/exercism/docs/blob/main/building/markdown/widgets.md) & [additions](https://github.com/exercism/docs/blob/main/building/markdown/internal-linking.md). Here is our full [Markdown Specification](https://github.com/exercism/docs/blob/main/building/markdown/markdown.md). We format/lint our Markdown with [Prettier](https://prettier.io/). + + + +## A Little More on Exercises + +- Each exercise must stand on its own. Please do not use or reference files outside the exercise directory. "Outside" files will not be included if a student fetches the exercise via the CLI. + +- Each exercise/problem should have a complete test suite, an example/exemplar solution, and a stub file ready for student implementation. + + - See [Concept Exercise Anatomy](https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md), or [Practice Exercise Anatomy](https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md) depending on to which type of exercise you are contributing. + +- For **practice exercises**, descriptions and instructions come from a centralized cross-track [problem specifications](https://github.com/exercism/problem-specifications) repository. Any updates or changes need to be proposed/approved in that repository first. If Python-specific changes become necessary, they need to be appended to the canonical instructions by creating a `instructions.append.md` file in this repository. + +- **Practice Exericse Test Suits** for many exercises are similarly [auto-generated]() from data in [problem specifications](https://github.com/exercism/problem-specifications). **Any changes to them need to be proposed/discussed in that repository, and approved by 3 track maintainers.** If Python-specific changes become necessary, they can be appended to this tracks `tests.toml` file. πŸ“› [**Please file an issue**](https://github.com/exercism/python/issues/new/choose)  πŸ“›Β  and check with maintainers before adding any Python-specific tests. + + + +## Python Coding Standards + + + + + +## Python Versions + +Exercises on this track officially support Python >= `3.8` Track tooling (`test runners`, `analyzers`, and r`epresenters`) all run on Python `3.9`. + +* All exercises going forward should be written for compatibility with Python >= `3.8`,. +* Version backward _incompatibility_ (*e.g* an exercise using a `3.8` or `3.9` only feature) should be clearly notied in any exercise introduction or notes. + +* _Most_ exercises will work with Python 3.6+, and _many_ are compatible with Python 2.7+. Please do not change existing exercises to add new `3.6`+ features without consulting with a maintainer first. + +- All test suites and example solutions must work in all Python versions that we currently support. When in doubt about a feature, please check with maintainers. + + + +## External Libraries and Dependencies + + + + + +## Auto-Generated Test Files and Test Templates + + + +Practice exericses inherit their definitions from the [problem-specifications](https://github.com/exercism/problem-specifications) repository in the form of _description files_. Exercise introductions, instructions and (_in the case of **many**, but not **all**_) test files are machine-generated . + +Changes to practice exercise _specifications_ should be raised/PR'd in [problem-specifications](https://github.com/exercism/problem-specifications) and approved by **3 track maintainers**. After an exercise change has gone through that process , related documents and tests for the Python track will need to be re-generated via [configlet](https://github.com/exercism/docs/blob/main/building/configlet/generating-documents.md). Configlet is also used as part of the track CI, essential track and exercise linting, and other verification tasks. + +If a practice exercise has an auto-generated `_test.py` file, there will be a `.meta/template.j2` and a `.meta/tests.toml` file in the exercise directory. If an exercise implements Python track-specific tests, there may be a `.meta/additional_tests.json` to define them. These `additional_tests.json` files will automatically be included in test generation. + +Practice exercise `_test.py` files are generated/regenerated via the [Python Track Test Generator](https://github.com/exercism/python/blob/main/docs/GENERATOR.md). Please reach out to a maintainer if you need any help with the process. + + + +## Tools and Tooling + + +################################## ## Architecture From b5192bc3373c3b837f90c8b531098dcc2b16ce67 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Tue, 5 Oct 2021 15:04:39 -0700 Subject: [PATCH 02/31] Formatting Update It was making me crazy. --- CONTRIBUTING.md | 55 +++++++++++++++++++++++++++++-------------------- 1 file changed, 33 insertions(+), 22 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 14de14cce7..d5019bfcde 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,42 +1,45 @@ # Contributing -πŸ‘‹πŸ½ πŸ‘‹ Hi. Thank you so much for your interest in contributing to the Python track! **We are happy you are here.**🌟 :tada: +Hi.  πŸ‘‹πŸ½  πŸ‘‹   + +Thank you so much for your interest in contributing to the Python track! **We are happy you are here.** 🌟   πŸŽ‰ `exercsim/Python` is one of the many tracks on [exercism](https://exercism.org/). This repo holds all the instructions, tests, code, & support files for Python *exercises* currently under development or implemented & available for students. Exercises are grouped into **concept** exercises which teach the [Python syllabus](https://exercism.org/tracks/python/concepts), and **practice** exercises, which are unlocked by progressing in the syllabus tree. Practice exercises are open-ended, and can be used to practice concepts learned, try out new techniques, and _play_. These two exercise groupings can be found in the track [`config.json`](https://github.com/exercism/javascript/blob/main/config.json), and under the `python/exercises` directory. +
- -#### πŸ› **Did you find a bug?** +## πŸ› **Did you find a bug?** It's not uncommon that people discover typos, confusing directions, or incorrect implementations of certain tests or code examples. Or you might have a great suggestion for a hint to aid students (πŸ’™) , see optimizations for exemplar or test code, find some missing test cases to add, or want to correct factual and/or logical errors. Or maybe you have a great idea for an exercise or feature. -_Our track is always a work in progress!_ 🌟🌟 Please πŸ“› [Open an issue](https://github.com/exercism/python/issues/new/choose)  πŸ“› , and let us know what you've found. +_Our track is always a work in progress!_ 🌟🌟 +Please πŸ“›  [Open an issue](https://github.com/exercism/python/issues/new/choose) πŸ“› , and let us know what you've found. +
- -#### 🚧 **Did you write a patch that fixes a bug? ** +## 🚧 **Did you write a patch that fixes a bug?** πŸ’› πŸ’™ **We Warmly Welcome Pull Requests that are:** -             1️⃣    Small, contained fixes for typos/grammar/punctuation/code syntax on [one] exercise, +             1️⃣    Small, contained fixes for typos/grammar/punctuation/code syntax on [one] exercise,              2️⃣     Medium changes that have been agreed/discussed via a filed issue, -             3️⃣     Contributions from our [help wanted](https://github.com/exercism/python/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) issue list, +             3️⃣     Contributions from our [help wanted](https://github.com/exercism/python/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) issue list,              4️⃣     Larger (_and previously agreed-upon_) contributions from recent & regular (_within the last 6 months_) contributors. -When in doubt, πŸ“› [Open an issue](https://github.com/exercism/python/issues/new/choose)  πŸ“›. We'll happily discuss your proposed change. 🐍 - -But let's talk before you take a whole lot of time implementing anything. +When in doubt, πŸ“›  [Open an issue](https://github.com/exercism/python/issues/new/choose) πŸ“›. We'll happily discuss your proposed change. 🐍 +But let's talk before you take a whole lot of time implementing anything. +
-#### :books: **Want to jump directly into Exercism specifications & detail? ** +## :books: **Want to jump directly into Exercism specifications & detail?** [Track Structure](https://github.com/exercism/docs/tree/main/building/tracks) **|** [Tasks](https://exercism.org/docs/building/product/tasks) **|** [Concepts](https://github.com/exercism/docs/blob/main/building/tracks/concepts.md) **|** [Concept Exercises](https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md) **|** [Practice Exercises](https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md) **|** [Presentation](https://github.com/exercism/docs/blob/main/building/tracks/presentation.md) **|** [ Style Guide for Writing](https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md) **|** [Markdown Specification](https://github.com/exercism/docs/blob/main/building/markdown/markdown.md) - +
## The Exercism Community @@ -48,11 +51,11 @@ But let's talk before you take a whole lot of time implementing anything. Some defined roles in our community: [Community Member](https://github.com/exercism/docs/tree/main/community/good-member) | [Contributors](https://github.com/exercism/docs/blob/main/community/contributors.md) |[Mentors](https://github.com/exercism/docs/tree/main/mentoring) | [Maintainers](https://github.com/exercism/docs/blob/main/community/maintainers.md) | [Admins](https://github.com/exercism/docs/blob/main/community/administrators.md) - +
## In General - +
- Pull requests should be focused on a single exercise, issue, or change. - PR titles and descriptions should make clear **what** has changed and **why**. Please link πŸ”— to any related issues the PR addresses. @@ -62,11 +65,11 @@ Some defined roles in our community: [Community Member](https://github.com/exer - Watch out otherwise for trailing spaces, extra blank lines, and spaces in blank lines. ⚠️ - The CI is going to run **a lot** of check on your PR. Pay attention to the failures, try to understand and fix them. If you need help, comment in the PR or issue. πŸ™‹πŸ½β€β™€οΈ - +
## A Little More on Writing Style and Standards - +
Non-code content (_exercise introductions & instructions, hints, concept write-ups, documentation etc._) should be written in [American English](https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md) . We strive to watch [the words we use](https://github.com/exercism/docs/blob/main/community/good-member/words.md). @@ -75,9 +78,12 @@ When a usage is contested or ambiguous, we default to what is best understood by Our documents use [Markdown](https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf) , with certain [alterations](https://github.com/exercism/docs/blob/main/building/markdown/widgets.md) & [additions](https://github.com/exercism/docs/blob/main/building/markdown/internal-linking.md). Here is our full [Markdown Specification](https://github.com/exercism/docs/blob/main/building/markdown/markdown.md). We format/lint our Markdown with [Prettier](https://prettier.io/). +
## A Little More on Exercises +
+ - Each exercise must stand on its own. Please do not use or reference files outside the exercise directory. "Outside" files will not be included if a student fetches the exercise via the CLI. - Each exercise/problem should have a complete test suite, an example/exemplar solution, and a stub file ready for student implementation. @@ -89,15 +95,19 @@ Our documents use [Markdown](https://guides.github.com/pdfs/markdown-cheatsheet- - **Practice Exericse Test Suits** for many exercises are similarly [auto-generated]() from data in [problem specifications](https://github.com/exercism/problem-specifications). **Any changes to them need to be proposed/discussed in that repository, and approved by 3 track maintainers.** If Python-specific changes become necessary, they can be appended to this tracks `tests.toml` file. πŸ“› [**Please file an issue**](https://github.com/exercism/python/issues/new/choose)  πŸ“›Β  and check with maintainers before adding any Python-specific tests. +
## Python Coding Standards +
- +
## Python Versions +
+ Exercises on this track officially support Python >= `3.8` Track tooling (`test runners`, `analyzers`, and r`epresenters`) all run on Python `3.9`. * All exercises going forward should be written for compatibility with Python >= `3.8`,. @@ -107,17 +117,18 @@ Exercises on this track officially support Python >= `3.8` Track tooling (`test - All test suites and example solutions must work in all Python versions that we currently support. When in doubt about a feature, please check with maintainers. - +
## External Libraries and Dependencies - +
+
## Auto-Generated Test Files and Test Templates - +
Practice exericses inherit their definitions from the [problem-specifications](https://github.com/exercism/problem-specifications) repository in the form of _description files_. Exercise introductions, instructions and (_in the case of **many**, but not **all**_) test files are machine-generated . @@ -127,7 +138,7 @@ If a practice exercise has an auto-generated `_test.py` file, there wi Practice exercise `_test.py` files are generated/regenerated via the [Python Track Test Generator](https://github.com/exercism/python/blob/main/docs/GENERATOR.md). Please reach out to a maintainer if you need any help with the process. - +
## Tools and Tooling From 9ca1fa01611d137e353b1462b9d7f5ffee3799f4 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Tue, 5 Oct 2021 16:02:08 -0700 Subject: [PATCH 03/31] More edits to formatting and wording. --- CONTRIBUTING.md | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d5019bfcde..c594a49114 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -57,23 +57,28 @@ Some defined roles in our community: [Community Member](https://github.com/exer
+- Maintainers are happy to review your work and help you out.  πŸ’› πŸ’™  But they may be in a different timezone, or tied up  πŸ§Ά  with other tasks. **Please wait at least 72 hours before pinging them.** They will review your request as soon as they are able to. +- If you'd like in-progress feedback or discussion, please mark your PR as a `[draft]` - Pull requests should be focused on a single exercise, issue, or change. -- PR titles and descriptions should make clear **what** has changed and **why**. Please link πŸ”— to any related issues the PR addresses. -- πŸ“› [An issue should be opened](https://github.com/exercism/python/issues/new/choose) πŸ“› _**before**_ creating a PR that makes significant or breaking change to an existing exercise. The same holds true for changes across multiple exercises. It is best to discuss these changes with 🧰 maintainers before doing the work. -- Follow coding standards found in [PEP8](https://www.python.org/dev/peps/pep-0008/) ( ["For Humans" version here](https://pep8.org/).) We do have some more specific requirements. More on that later. + +- Pull Request titles and descriptions should make clear **what** has changed and **why**. Please link  πŸ”—  to any related issues the PR addresses. +- πŸ“› [An issue should be opened](https://github.com/exercism/python/issues/new/choose) πŸ“›  _**before**_ creating a Pull Request that makes significant or breaking changes to an existing exercise. + - The same holds true for changes across multiple exercises. + - It is best to discuss changes with  πŸ§° maintainers before doing a lot of work. +- Follow coding standards found in [PEP8](https://www.python.org/dev/peps/pep-0008/) ( ["For Humans" version here](https://pep8.org/).) We do have some more specific requirements. More on that a little later. - All files should have a proper [EOL](https://en.wikipedia.org/wiki/Newline) at the end. This means one carriage return at the end of the final line of text in files. -- Watch out otherwise for trailing spaces, extra blank lines, and spaces in blank lines. ⚠️ -- The CI is going to run **a lot** of check on your PR. Pay attention to the failures, try to understand and fix them. If you need help, comment in the PR or issue. πŸ™‹πŸ½β€β™€οΈ +- Otherwise, watch out  βš οΈ  for trailing spaces, extra blank lines, extra spaces, and spaces in blank lines. +- The CI is going to run **a lot** of checks on your PR. Pay attention to the failures, try to understand and fix them. If you need help, comment in the PR or issue.  πŸ™‹πŸ½β€β™€οΈ   The maintainers are happy to help troubleshoot.
-## A Little More on Writing Style and Standards +## A Little More on Prose Writing Style and Standards
Non-code content (_exercise introductions & instructions, hints, concept write-ups, documentation etc._) should be written in [American English](https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md) . We strive to watch [the words we use](https://github.com/exercism/docs/blob/main/community/good-member/words.md). -When a usage is contested or ambiguous, we default to what is best understood by our international community of learners, even if it "sounds a little weird" to a "native" American English speaker. +When a word or phrase usage is contested or ambiguous, we default to what is best understood by our international community of learners, even if it "sounds a little weird" to a "native" American English speaker. Our documents use [Markdown](https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf) , with certain [alterations](https://github.com/exercism/docs/blob/main/building/markdown/widgets.md) & [additions](https://github.com/exercism/docs/blob/main/building/markdown/internal-linking.md). Here is our full [Markdown Specification](https://github.com/exercism/docs/blob/main/building/markdown/markdown.md). We format/lint our Markdown with [Prettier](https://prettier.io/). @@ -84,15 +89,20 @@ Our documents use [Markdown](https://guides.github.com/pdfs/markdown-cheatsheet-
-- Each exercise must stand on its own. Please do not use or reference files outside the exercise directory. "Outside" files will not be included if a student fetches the exercise via the CLI. +- Each exercise must be self-contained. Please do not use or reference files that reside outside the given exercise directory. "Outside" files will not be included if a student fetches the exercise via the CLI. + +- Each exercise/problem should include a complete test suite, an example/exemplar solution, and a stub file ready for student implementation. -- Each exercise/problem should have a complete test suite, an example/exemplar solution, and a stub file ready for student implementation. + - See [Concept Exercise Anatomy](https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md), or [Practice Exercise Anatomy](https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md) depending on which type of exercise you are contributing to. - - See [Concept Exercise Anatomy](https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md), or [Practice Exercise Anatomy](https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md) depending on to which type of exercise you are contributing. +- For **practice exercise**, descriptions and instructions come from a centralized, cross-track [problem specifications](https://github.com/exercism/problem-specifications) repository. -- For **practice exercises**, descriptions and instructions come from a centralized cross-track [problem specifications](https://github.com/exercism/problem-specifications) repository. Any updates or changes need to be proposed/approved in that repository first. If Python-specific changes become necessary, they need to be appended to the canonical instructions by creating a `instructions.append.md` file in this repository. + - Any updates or changes need to be proposed/approved in `problem-specifications` first. + - If Python-specific changes become necessary, they need to be appended to the canonical instructions by creating a `instructions.append.md` file in this (`exercism/Python`) repository. -- **Practice Exericse Test Suits** for many exercises are similarly [auto-generated]() from data in [problem specifications](https://github.com/exercism/problem-specifications). **Any changes to them need to be proposed/discussed in that repository, and approved by 3 track maintainers.** If Python-specific changes become necessary, they can be appended to this tracks `tests.toml` file. πŸ“› [**Please file an issue**](https://github.com/exercism/python/issues/new/choose)  πŸ“›Β  and check with maintainers before adding any Python-specific tests. +- **Practice Exericse Test Suits** for many practice exercises are similarly [auto-generated](##Auto-Generated Test Files and Test Templates) from data in [problem specifications](https://github.com/exercism/problem-specifications). + - Any changes to them need to be proposed/discussed in the `problem-specifications` repository and approved by **3 track maintainers**, since changes could potentially affect many (or all) exercism language tracks. + - If Python-specific test changes become necessary, they can be appended to the exercise `tests.toml` file. πŸ“› [**Please file an issue**](https://github.com/exercism/python/issues/new/choose) πŸ“›   and check with maintainers before adding any Python-specific tests.
From f1496ebaf1b7e68fc0d3e79e8d9176565783a029 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Tue, 5 Oct 2021 16:09:45 -0700 Subject: [PATCH 04/31] More formatting niggles. --- CONTRIBUTING.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c594a49114..ef71c3d473 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,7 +13,7 @@ Exercises are grouped into **concept** exercises which teach the [Python syllab ## πŸ› **Did you find a bug?** -It's not uncommon that people discover typos, confusing directions, or incorrect implementations of certain tests or code examples. Or you might have a great suggestion for a hint to aid students (πŸ’™) , see optimizations for exemplar or test code, find some missing test cases to add, or want to correct factual and/or logical errors. Or maybe you have a great idea for an exercise or feature. +It's not uncommon that people discover typos, confusing directions, or incorrect implementations of certain tests or code examples. Or you might have a great suggestion for a hint to aid students (πŸ’™  ) , see optimizations for exemplar or test code, find some missing test cases to add, or want to correct factual and/or logical errors. Or maybe you have a great idea for an exercise or feature. _Our track is always a work in progress!_ 🌟🌟 Please πŸ“›  [Open an issue](https://github.com/exercism/python/issues/new/choose) πŸ“› , and let us know what you've found. @@ -57,14 +57,13 @@ Some defined roles in our community: [Community Member](https://github.com/exer
-- Maintainers are happy to review your work and help you out.  πŸ’› πŸ’™  But they may be in a different timezone, or tied up  πŸ§Ά  with other tasks. **Please wait at least 72 hours before pinging them.** They will review your request as soon as they are able to. +- Maintainers are happy to review your work and help you out. πŸ’› πŸ’™  But they may be in a different timezone, or tied up  πŸ§Ά  with other tasks. **Please wait at least 72 hours before pinging them.** They will review your request as soon as they are able to. - If you'd like in-progress feedback or discussion, please mark your PR as a `[draft]` - Pull requests should be focused on a single exercise, issue, or change. - - Pull Request titles and descriptions should make clear **what** has changed and **why**. Please link  πŸ”—  to any related issues the PR addresses. -- πŸ“› [An issue should be opened](https://github.com/exercism/python/issues/new/choose) πŸ“›  _**before**_ creating a Pull Request that makes significant or breaking changes to an existing exercise. +- πŸ“› [An issue should be opened](https://github.com/exercism/python/issues/new/choose) πŸ“›  _**before**_ creating a Pull Request making significant or breaking changes to an existing exercise. - The same holds true for changes across multiple exercises. - - It is best to discuss changes with  πŸ§° maintainers before doing a lot of work. + - It is best to discuss changes with  πŸ§°  maintainers before doing a lot of work. - Follow coding standards found in [PEP8](https://www.python.org/dev/peps/pep-0008/) ( ["For Humans" version here](https://pep8.org/).) We do have some more specific requirements. More on that a little later. - All files should have a proper [EOL](https://en.wikipedia.org/wiki/Newline) at the end. This means one carriage return at the end of the final line of text in files. - Otherwise, watch out  βš οΈ  for trailing spaces, extra blank lines, extra spaces, and spaces in blank lines. From 37c915cbb60909fa40008b0bc9ea8e034b70fde1 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Tue, 5 Oct 2021 17:48:18 -0700 Subject: [PATCH 05/31] Changed internal links to reflinks. --- CONTRIBUTING.md | 95 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 67 insertions(+), 28 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ef71c3d473..4705bc9fbd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,9 +5,9 @@ Hi.  πŸ‘‹πŸ½  πŸ‘‹   Thank you so much for your interest in contributing to the Python track! **We are happy you are here.** 🌟   πŸŽ‰ -`exercsim/Python` is one of the many tracks on [exercism](https://exercism.org/). This repo holds all the instructions, tests, code, & support files for Python *exercises* currently under development or implemented & available for students. +`exercsim/Python` is one of the many tracks on [exercism][exercism-website]. This repo holds all the instructions, tests, code, & support files for Python *exercises* currently under development or implemented & available for students. -Exercises are grouped into **concept** exercises which teach the [Python syllabus](https://exercism.org/tracks/python/concepts), and **practice** exercises, which are unlocked by progressing in the syllabus tree. Practice exercises are open-ended, and can be used to practice concepts learned, try out new techniques, and _play_. These two exercise groupings can be found in the track [`config.json`](https://github.com/exercism/javascript/blob/main/config.json), and under the `python/exercises` directory. +Exercises are grouped into **concept** exercises which teach the [Python syllabus][python-syllabus], and **practice** exercises, which are unlocked by progressing in the syllabus tree. Practice exercises are open-ended, and can be used to practice concepts learned, try out new techniques, and _play_. These two exercise groupings can be found in the track [`config.json`][config-json], and under the `python/exercises` directory.
@@ -16,20 +16,20 @@ Exercises are grouped into **concept** exercises which teach the [Python syllab It's not uncommon that people discover typos, confusing directions, or incorrect implementations of certain tests or code examples. Or you might have a great suggestion for a hint to aid students (πŸ’™  ) , see optimizations for exemplar or test code, find some missing test cases to add, or want to correct factual and/or logical errors. Or maybe you have a great idea for an exercise or feature. _Our track is always a work in progress!_ 🌟🌟 -Please πŸ“›  [Open an issue](https://github.com/exercism/python/issues/new/choose) πŸ“› , and let us know what you've found. +Please πŸ“›  [Open an issue][open-an-issue] πŸ“› , and let us know what you've found.
## 🚧 **Did you write a patch that fixes a bug?** - πŸ’› πŸ’™ **We Warmly Welcome Pull Requests that are:** + πŸ’› πŸ’™  **We Warmly Welcome Pull Requests that are:** -             1️⃣    Small, contained fixes for typos/grammar/punctuation/code syntax on [one] exercise, +             1️⃣     Small, contained fixes for typos/grammar/punctuation/code syntax on [one] exercise,              2️⃣     Medium changes that have been agreed/discussed via a filed issue, -             3️⃣     Contributions from our [help wanted](https://github.com/exercism/python/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) issue list, +             3️⃣     Contributions from our [help wanted][help-wanted] issue list,              4️⃣     Larger (_and previously agreed-upon_) contributions from recent & regular (_within the last 6 months_) contributors. -When in doubt, πŸ“›  [Open an issue](https://github.com/exercism/python/issues/new/choose) πŸ“›. We'll happily discuss your proposed change. 🐍 +When in doubt, πŸ“›  [Open an issue][open-an-issue] πŸ“›. We will happily discuss your proposed change. 🐍 But let's talk before you take a whole lot of time implementing anything. @@ -37,19 +37,22 @@ But let's talk before you take a whole lot of time implementing anything. ## :books: **Want to jump directly into Exercism specifications & detail?** -[Track Structure](https://github.com/exercism/docs/tree/main/building/tracks) **|** [Tasks](https://exercism.org/docs/building/product/tasks) **|** [Concepts](https://github.com/exercism/docs/blob/main/building/tracks/concepts.md) **|** [Concept Exercises](https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md) **|** [Practice Exercises](https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md) **|** [Presentation](https://github.com/exercism/docs/blob/main/building/tracks/presentation.md) **|** [ Style Guide for Writing](https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md) **|** [Markdown Specification](https://github.com/exercism/docs/blob/main/building/markdown/markdown.md) +✨ πŸ¦„  Here is the good stuff: -
+[Track Structure][exercism-track-structure] **|** [Tasks][exercism-tasks] **|** [Concepts][exercism-concepts] **|** [Concept Exercises][concept-exercises] **|** [Practice Exercises][practice-exercises] **|** [Presentation][exercise-presentation] **|** [ Style Guide for Writing][exercism-writing-style] **|** [Markdown Specification][exercism-markdown-specification] -## The Exercism Community +Web-formatted  πŸ•ΈοΈ   versions are available in the [contributing section][website-contributing-section] of exercsim.org. +
+## 🌍   The Exercism Community   🌏 -🌟🌟 If you have not already done so, please take a moment to read our [Code of Conduct](https://exercism.org/docs/using/legal/code-of-conduct) & [Being a Good Community Member](https://github.com/exercism/docs/tree/main/community/good-member) . It might also be helpful to take a look at [The words that we use](https://github.com/exercism/docs/blob/main/community/good-member/words.md). +
+🌟🌟 If you have not already done so, please take a moment to read our [Code of Conduct][exercism-code-of-conduct] & [Being a Good Community Member][being-a-good-community-member]. It might also be helpful to take a look at [The words that we use][the-words-that-we-use]. -Some defined roles in our community: [Community Member](https://github.com/exercism/docs/tree/main/community/good-member) | [Contributors](https://github.com/exercism/docs/blob/main/community/contributors.md) |[Mentors](https://github.com/exercism/docs/tree/main/mentoring) | [Maintainers](https://github.com/exercism/docs/blob/main/community/maintainers.md) | [Admins](https://github.com/exercism/docs/blob/main/community/administrators.md) +Some defined roles in our community: [Community Member][being-a-good-community-member] | [Contributors][exercism-contributors] | [Mentors][exercism-mentors] | [Maintainers][exercism-track-maintainers] | [Admins][exercism-admins]
@@ -58,14 +61,14 @@ Some defined roles in our community: [Community Member](https://github.com/exer
- Maintainers are happy to review your work and help you out. πŸ’› πŸ’™  But they may be in a different timezone, or tied up  πŸ§Ά  with other tasks. **Please wait at least 72 hours before pinging them.** They will review your request as soon as they are able to. -- If you'd like in-progress feedback or discussion, please mark your PR as a `[draft]` +- If you'd like in-progress feedback or discussion, please mark your Pull Request as a `[draft]` - Pull requests should be focused on a single exercise, issue, or change. - Pull Request titles and descriptions should make clear **what** has changed and **why**. Please link  πŸ”—  to any related issues the PR addresses. -- πŸ“› [An issue should be opened](https://github.com/exercism/python/issues/new/choose) πŸ“›  _**before**_ creating a Pull Request making significant or breaking changes to an existing exercise. +- πŸ“› [An issue should be opened][open-an-issue] πŸ“›  _**before**_ creating a Pull Request making significant or breaking changes to an existing exercise. - The same holds true for changes across multiple exercises. - It is best to discuss changes with  πŸ§°  maintainers before doing a lot of work. -- Follow coding standards found in [PEP8](https://www.python.org/dev/peps/pep-0008/) ( ["For Humans" version here](https://pep8.org/).) We do have some more specific requirements. More on that a little later. -- All files should have a proper [EOL](https://en.wikipedia.org/wiki/Newline) at the end. This means one carriage return at the end of the final line of text in files. +- Follow coding standards found in [PEP8][PEP8] ( ["For Humans" version here][pep8-for-humans]. We do have some more specific requirements. More on that a little later. +- All files should have a proper [EOL][EOL] at the end. This means one carriage return at the end of the final line of text in files. - Otherwise, watch out  βš οΈ  for trailing spaces, extra blank lines, extra spaces, and spaces in blank lines. - The CI is going to run **a lot** of checks on your PR. Pay attention to the failures, try to understand and fix them. If you need help, comment in the PR or issue.  πŸ™‹πŸ½β€β™€οΈ   The maintainers are happy to help troubleshoot. @@ -75,11 +78,11 @@ Some defined roles in our community: [Community Member](https://github.com/exer
-Non-code content (_exercise introductions & instructions, hints, concept write-ups, documentation etc._) should be written in [American English](https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md) . We strive to watch [the words we use](https://github.com/exercism/docs/blob/main/community/good-member/words.md). +Non-code content (_exercise introductions & instructions, hints, concept write-ups, documentation etc._) should be written in [American English][american-english]. We strive to watch [the words we use][the-words-we-use]. -When a word or phrase usage is contested or ambiguous, we default to what is best understood by our international community of learners, even if it "sounds a little weird" to a "native" American English speaker. +When a word or phrase usage is contested | ambiguous, we default to what is best understood by our international community of learners, even if it "sounds a little weird" to a "native" American English speaker. -Our documents use [Markdown](https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf) , with certain [alterations](https://github.com/exercism/docs/blob/main/building/markdown/widgets.md) & [additions](https://github.com/exercism/docs/blob/main/building/markdown/internal-linking.md). Here is our full [Markdown Specification](https://github.com/exercism/docs/blob/main/building/markdown/markdown.md). We format/lint our Markdown with [Prettier](https://prettier.io/). +Our documents use [Markdown][markdown-language], with certain [alterations][exercism-markdown-widgets] & [additions][exercism-internal-linking]. Here is our full [Markdown Specification][exercism-markdown-specification]. We format/lint our Markdown with [Prettier][prettier].
@@ -92,16 +95,16 @@ Our documents use [Markdown](https://guides.github.com/pdfs/markdown-cheatsheet- - Each exercise/problem should include a complete test suite, an example/exemplar solution, and a stub file ready for student implementation. - - See [Concept Exercise Anatomy](https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md), or [Practice Exercise Anatomy](https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md) depending on which type of exercise you are contributing to. + - See [Concept Exercise Anatomy][concept-exercise-anatomy], or [Practice Exercise Anatomy][practice-exercise-anatomy] depending on which type of exercise you are contributing to. -- For **practice exercise**, descriptions and instructions come from a centralized, cross-track [problem specifications](https://github.com/exercism/problem-specifications) repository. +- For **practice exercise**, descriptions and instructions come from a centralized, cross-track [problem specifications][problem-specifications] repository. - Any updates or changes need to be proposed/approved in `problem-specifications` first. - If Python-specific changes become necessary, they need to be appended to the canonical instructions by creating a `instructions.append.md` file in this (`exercism/Python`) repository. -- **Practice Exericse Test Suits** for many practice exercises are similarly [auto-generated](##Auto-Generated Test Files and Test Templates) from data in [problem specifications](https://github.com/exercism/problem-specifications). - - Any changes to them need to be proposed/discussed in the `problem-specifications` repository and approved by **3 track maintainers**, since changes could potentially affect many (or all) exercism language tracks. - - If Python-specific test changes become necessary, they can be appended to the exercise `tests.toml` file. πŸ“› [**Please file an issue**](https://github.com/exercism/python/issues/new/choose) πŸ“›   and check with maintainers before adding any Python-specific tests. +- **Practice Exericse Test Suits** for many practice exercises are similarly [auto-generated](##Auto-Generated Test Files and Test Templates) from data in [problem specifications][problem-specifications]. + - Any changes to them need to be proposed/discussed in the `problem-specifications` repository and approved by **3 track maintainers**, since changes could potentially affect many (_or all_) exercism language tracks. + - If Python-specific test changes become necessary, they can be appended to the exercise `tests.toml` file. πŸ“› [**Please file an issue**][open-an-issue] πŸ“›   and check with maintainers before adding any Python-specific tests.
@@ -139,13 +142,13 @@ Exercises on this track officially support Python >= `3.8` Track tooling (`test
-Practice exericses inherit their definitions from the [problem-specifications](https://github.com/exercism/problem-specifications) repository in the form of _description files_. Exercise introductions, instructions and (_in the case of **many**, but not **all**_) test files are machine-generated . +Practice exericses inherit their definitions from the [problem-specifications][problem-specifications] repository in the form of _description files_. Exercise introductions, instructions and (_in the case of **many**, but not **all**_) test files are machine-generated . -Changes to practice exercise _specifications_ should be raised/PR'd in [problem-specifications](https://github.com/exercism/problem-specifications) and approved by **3 track maintainers**. After an exercise change has gone through that process , related documents and tests for the Python track will need to be re-generated via [configlet](https://github.com/exercism/docs/blob/main/building/configlet/generating-documents.md). Configlet is also used as part of the track CI, essential track and exercise linting, and other verification tasks. +Changes to practice exercise _specifications_ should be raised/PR'd in [problem-specifications][problem-specifications] and approved by **3 track maintainers**. After an exercise change has gone through that process , related documents and tests for the Python track will need to be re-generated via [configlet][configlet]. Configlet is also used as part of the track CI, essential track and exercise linting, and other verification tasks. -If a practice exercise has an auto-generated `_test.py` file, there will be a `.meta/template.j2` and a `.meta/tests.toml` file in the exercise directory. If an exercise implements Python track-specific tests, there may be a `.meta/additional_tests.json` to define them. These `additional_tests.json` files will automatically be included in test generation. +If a practice exercise has an auto-generated `_test.py` file, there will be a `.meta/template.j2` and a `.meta/tests.toml` file in the exercise directory. If an exercise implements Python track-specific tests, there may be a `.meta/additional_tests.json` to define them. These `additional_tests.json` files will automatically be included in test generation. -Practice exercise `_test.py` files are generated/regenerated via the [Python Track Test Generator](https://github.com/exercism/python/blob/main/docs/GENERATOR.md). Please reach out to a maintainer if you need any help with the process. +Practice exercise `_test.py` files are generated/regenerated via the [Python Track Test Generator][python-track-test-generator]. Please reach out to a maintainer if you need any help with the process.
@@ -298,3 +301,39 @@ Before committing: [problem-specifications]: https://github.com/exercism/problem-specifications [topics list]: https://github.com/exercism/problem-specifications/blob/master/TOPICS.txt [flake8]: http://flake8.pycqa.org/ + +[EOL]: (https://en.wikipedia.org/wiki/Newline) +[PEP8]: (https://www.python.org/dev/peps/pep-0008/) +[american-english]: (https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md) +[being-a-good-community-member]: (https://github.com/exercism/docs/tree/main/community/good-member) +[concept-exercise-anatomy]: (https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md) +[concept-exercises]: (https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md) +[config-json]: (https://github.com/exercism/javascript/blob/main/config.json) +[configlet]: (https://github.com/exercism/docs/blob/main/building/configlet/generating-documents.md) +[exercise-presentation]: (https://github.com/exercism/docs/blob/main/building/tracks/presentation.md) +[exercism-admins]: (https://github.com/exercism/docs/blob/main/community/administrators.md) +[exercism-code-of-conduct]: (https://exercism.org/docs/using/legal/code-of-conduct) +[exercism-concepts]: (https://github.com/exercism/docs/blob/main/building/tracks/concepts.md) +[exercism-internal-linking]: (https://github.com/exercism/docs/blob/main/building/markdown/internal-linking.md) +[exercism-markdown-specification]: (https://github.com/exercism/docs/blob/main/building/markdown/markdown.md) +[exercism-markdown-widgets]: (https://github.com/exercism/docs/blob/main/building/markdown/widgets.md) +[exercism-mentors]: (https://github.com/exercism/docs/tree/main/mentoring) +[exercism-contributors]: (https://github.com/exercism/docs/blob/main/community/contributors.md) +[exercism-tasks]: (https://exercism.org/docs/building/product/tasks) +[exercism-track-maintainers]: (https://github.com/exercism/docs/blob/main/community/maintainers.md) +[exercism-track-structure]: (https://github.com/exercism/docs/tree/main/building/tracks) +[exercism-website]: (https://exercism.org/) +[exercism-writing-style]: (https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md) +[help-wanted]: (https://github.com/exercism/python/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) +[markdown-language]: (https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf) +[markdown-specification]: (https://github.com/exercism/docs/blob/main/building/markdown/markdown.md) +[open-an-issue]: (https://github.com/exercism/python/issues/new/choose) +[practice-exercise-anatomy]: (https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md) +[practice-exercises]: (https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md) +[prettier]: (https://prettier.io/) +[problem-specifications]: (https://github.com/exercism/problem-specifications) +[python-syllabus]: (https://exercism.org/tracks/python/concepts) +[python-track-test-generator]: (https://github.com/exercism/python/blob/main/docs/GENERATOR.md) +[the-words-that-we-use]: (https://github.com/exercism/docs/blob/main/community/good-member/words.md) +[website-contributing-section]:(https://exercism.org/docs/building) + [pep8-for-humans]: (https://pep8.org/) \ No newline at end of file From 1885c2174f67a6f7d1c395e21f658762a975828c Mon Sep 17 00:00:00 2001 From: BethanyG Date: Tue, 5 Oct 2021 17:57:31 -0700 Subject: [PATCH 06/31] fix broken links --- CONTRIBUTING.md | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4705bc9fbd..ae142c50b7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,7 @@ Thank you so much for your interest in contributing to the Python track! **We a `exercsim/Python` is one of the many tracks on [exercism][exercism-website]. This repo holds all the instructions, tests, code, & support files for Python *exercises* currently under development or implemented & available for students. -Exercises are grouped into **concept** exercises which teach the [Python syllabus][python-syllabus], and **practice** exercises, which are unlocked by progressing in the syllabus tree. Practice exercises are open-ended, and can be used to practice concepts learned, try out new techniques, and _play_. These two exercise groupings can be found in the track [`config.json`][config-json], and under the `python/exercises` directory. +Exercises are grouped into **concept** exercises which teach the [Python syllabus][python-syllabus], and **practice** exercises, which are unlocked by progressing in the syllabus tree. Practice exercises are open-ended, and can be used to practice concepts learned, try out new techniques, and _play_. These two exercise groupings can be found in the track [config.json][config-json], and under the `python/exercises` directory.
@@ -39,7 +39,7 @@ But let's talk before you take a whole lot of time implementing anything. ✨ πŸ¦„  Here is the good stuff: -[Track Structure][exercism-track-structure] **|** [Tasks][exercism-tasks] **|** [Concepts][exercism-concepts] **|** [Concept Exercises][concept-exercises] **|** [Practice Exercises][practice-exercises] **|** [Presentation][exercise-presentation] **|** [ Style Guide for Writing][exercism-writing-style] **|** [Markdown Specification][exercism-markdown-specification] +[Track Structure][exercism-track-structure] **|** [Tasks][exercism-tasks] **|** [Concepts][exercism-concepts] **|** [Concept Exercises][concept-exercises] **|** [Practice Exercises][practice-exercises] **|** [Presentation][exercise-presentation] **|** [ Style Guide for Writing][exercism-writing-style] **|** [Markdown Specification][exercism-markdown-specification] Web-formatted  πŸ•ΈοΈ   versions are available in the [contributing section][website-contributing-section] of exercsim.org. @@ -49,10 +49,10 @@ Web-formatted  πŸ•ΈοΈ   versions are available in the [contributing s
-🌟🌟 If you have not already done so, please take a moment to read our [Code of Conduct][exercism-code-of-conduct] & [Being a Good Community Member][being-a-good-community-member]. It might also be helpful to take a look at [The words that we use][the-words-that-we-use]. +🌟🌟  If you have not already done so, please take a moment to read our [Code of Conduct][exercism-code-of-conduct] & [Being a Good Community Member][being-a-good-community-member]. It might also be helpful to take a look at [The words that we use][the-words-that-we-use]. -Some defined roles in our community: [Community Member][being-a-good-community-member] | [Contributors][exercism-contributors] | [Mentors][exercism-mentors] | [Maintainers][exercism-track-maintainers] | [Admins][exercism-admins] +Some defined roles in our community: [Community Member][being-a-good-community-member] **|** [Contributors][exercism-contributors] **|** [Mentors][exercism-mentors] **|** [Maintainers][exercism-track-maintainers] **|** [Admins][exercism-admins]
@@ -72,6 +72,14 @@ Some defined roles in our community: [Community Member][being-a-good-community- - Otherwise, watch out  βš οΈ  for trailing spaces, extra blank lines, extra spaces, and spaces in blank lines. - The CI is going to run **a lot** of checks on your PR. Pay attention to the failures, try to understand and fix them. If you need help, comment in the PR or issue.  πŸ™‹πŸ½β€β™€οΈ   The maintainers are happy to help troubleshoot. + + βš οΈ **Before committing** βš οΈ  + +- Run `configlet fmt` and `configlet lint` before committing if [config.json](config-json) has been modified. +- Run [flake8][flake8] to ensure all Python code conforms to general style standards. +- Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly. +- If you modified or created a `hints.md` file, [regenerate the README](#generating-exercise-readmes) +
## A Little More on Prose Writing Style and Standards @@ -102,7 +110,7 @@ Our documents use [Markdown][markdown-language], with certain [alterations][exer - Any updates or changes need to be proposed/approved in `problem-specifications` first. - If Python-specific changes become necessary, they need to be appended to the canonical instructions by creating a `instructions.append.md` file in this (`exercism/Python`) repository. -- **Practice Exericse Test Suits** for many practice exercises are similarly [auto-generated](##Auto-Generated Test Files and Test Templates) from data in [problem specifications][problem-specifications]. +- **Practice Exericse Test Suits** for many practice exercises are similarly [auto-generated][##Auto-Generated Test Files and Test Templates] from data in [problem specifications][problem-specifications]. - Any changes to them need to be proposed/discussed in the `problem-specifications` repository and approved by **3 track maintainers**, since changes could potentially affect many (_or all_) exercism language tracks. - If Python-specific test changes become necessary, they can be appended to the exercise `tests.toml` file. πŸ“› [**Please file an issue**][open-an-issue] πŸ“›   and check with maintainers before adding any Python-specific tests. @@ -286,19 +294,11 @@ Fields Similar to implementing a canonical exercise that has no `canonical-data.json`, but the exercise README will also need to be written manually. Carefully follow the structure of generated exercise READMEs. -## Pull Request Tips -Before committing: -- Run `configlet fmt` and `configlet lint` before committing if [`config.json`](config.json) has been modified -- Run [flake8] to ensure all Python code conforms to style standards -- Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly -- If you modified or created a `hints.md` file, [regenerate the README](#generating-exercise-readmes) -- If your changes affect multiple exercises, try to break them up into a separate PR for each exercise. -[configlet]: https://github.com/exercism/configlet +[configlet-general]: https://github.com/exercism/configlet [Exercism contributing guide]: https://github.com/exercism/docs/blob/master/contributing-to-language-tracks/README.md -[problem-specifications]: https://github.com/exercism/problem-specifications [topics list]: https://github.com/exercism/problem-specifications/blob/master/TOPICS.txt [flake8]: http://flake8.pycqa.org/ @@ -326,7 +326,6 @@ Before committing: [exercism-writing-style]: (https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md) [help-wanted]: (https://github.com/exercism/python/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) [markdown-language]: (https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf) -[markdown-specification]: (https://github.com/exercism/docs/blob/main/building/markdown/markdown.md) [open-an-issue]: (https://github.com/exercism/python/issues/new/choose) [practice-exercise-anatomy]: (https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md) [practice-exercises]: (https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md) @@ -336,4 +335,4 @@ Before committing: [python-track-test-generator]: (https://github.com/exercism/python/blob/main/docs/GENERATOR.md) [the-words-that-we-use]: (https://github.com/exercism/docs/blob/main/community/good-member/words.md) [website-contributing-section]:(https://exercism.org/docs/building) - [pep8-for-humans]: (https://pep8.org/) \ No newline at end of file +[pep8-for-humans]: (https://pep8.org/) \ No newline at end of file From 6fabf337de0fb17fa0d24f8899e92824100d9837 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Tue, 5 Oct 2021 18:09:43 -0700 Subject: [PATCH 07/31] Fixed reflinks AGAIN --- CONTRIBUTING.md | 73 +++++++++++++++++++++++-------------------------- 1 file changed, 34 insertions(+), 39 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ae142c50b7..61f70af74b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -295,44 +295,39 @@ Similar to implementing a canonical exercise that has no `canonical-data.json`, - - +[EOL]: https://en.wikipedia.org/wiki/Newline +[PEP8]: https://www.python.org/dev/peps/pep-0008/ +[american-english]: https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md +[being-a-good-community-member]: https://github.com/exercism/docs/tree/main/community/good-member +[concept-exercise-anatomy]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md +[concept-exercises]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md +[config-json]: https://github.com/exercism/javascript/blob/main/config.json [configlet-general]: https://github.com/exercism/configlet -[Exercism contributing guide]: https://github.com/exercism/docs/blob/master/contributing-to-language-tracks/README.md -[topics list]: https://github.com/exercism/problem-specifications/blob/master/TOPICS.txt +[configlet]: https://github.com/exercism/docs/blob/main/building/configlet/generating-documents.md +[exercise-presentation]: https://github.com/exercism/docs/blob/main/building/tracks/presentation.md +[exercism-admins]: https://github.com/exercism/docs/blob/main/community/administrators.md +[exercism-code-of-conduct]: https://exercism.org/docs/using/legal/code-of-conduct +[exercism-concepts]: https://github.com/exercism/docs/blob/main/building/tracks/concepts.md +[exercism-contributors]: https://github.com/exercism/docs/blob/main/community/contributors.md +[exercism-internal-linking]: https://github.com/exercism/docs/blob/main/building/markdown/internal-linking.md +[exercism-markdown-specification]: https://github.com/exercism/docs/blob/main/building/markdown/markdown.md +[exercism-markdown-widgets]: https://github.com/exercism/docs/blob/main/building/markdown/widgets.md +[exercism-mentors]: https://github.com/exercism/docs/tree/main/mentoring +[exercism-tasks]: https://exercism.org/docs/building/product/tasks +[exercism-track-maintainers]: https://github.com/exercism/docs/blob/main/community/maintainers.md +[exercism-track-structure]: https://github.com/exercism/docs/tree/main/building/tracks +[exercism-website]: https://exercism.org/ +[exercism-writing-style]: https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md [flake8]: http://flake8.pycqa.org/ - -[EOL]: (https://en.wikipedia.org/wiki/Newline) -[PEP8]: (https://www.python.org/dev/peps/pep-0008/) -[american-english]: (https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md) -[being-a-good-community-member]: (https://github.com/exercism/docs/tree/main/community/good-member) -[concept-exercise-anatomy]: (https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md) -[concept-exercises]: (https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md) -[config-json]: (https://github.com/exercism/javascript/blob/main/config.json) -[configlet]: (https://github.com/exercism/docs/blob/main/building/configlet/generating-documents.md) -[exercise-presentation]: (https://github.com/exercism/docs/blob/main/building/tracks/presentation.md) -[exercism-admins]: (https://github.com/exercism/docs/blob/main/community/administrators.md) -[exercism-code-of-conduct]: (https://exercism.org/docs/using/legal/code-of-conduct) -[exercism-concepts]: (https://github.com/exercism/docs/blob/main/building/tracks/concepts.md) -[exercism-internal-linking]: (https://github.com/exercism/docs/blob/main/building/markdown/internal-linking.md) -[exercism-markdown-specification]: (https://github.com/exercism/docs/blob/main/building/markdown/markdown.md) -[exercism-markdown-widgets]: (https://github.com/exercism/docs/blob/main/building/markdown/widgets.md) -[exercism-mentors]: (https://github.com/exercism/docs/tree/main/mentoring) -[exercism-contributors]: (https://github.com/exercism/docs/blob/main/community/contributors.md) -[exercism-tasks]: (https://exercism.org/docs/building/product/tasks) -[exercism-track-maintainers]: (https://github.com/exercism/docs/blob/main/community/maintainers.md) -[exercism-track-structure]: (https://github.com/exercism/docs/tree/main/building/tracks) -[exercism-website]: (https://exercism.org/) -[exercism-writing-style]: (https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md) -[help-wanted]: (https://github.com/exercism/python/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) -[markdown-language]: (https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf) -[open-an-issue]: (https://github.com/exercism/python/issues/new/choose) -[practice-exercise-anatomy]: (https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md) -[practice-exercises]: (https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md) -[prettier]: (https://prettier.io/) -[problem-specifications]: (https://github.com/exercism/problem-specifications) -[python-syllabus]: (https://exercism.org/tracks/python/concepts) -[python-track-test-generator]: (https://github.com/exercism/python/blob/main/docs/GENERATOR.md) -[the-words-that-we-use]: (https://github.com/exercism/docs/blob/main/community/good-member/words.md) -[website-contributing-section]:(https://exercism.org/docs/building) -[pep8-for-humans]: (https://pep8.org/) \ No newline at end of file +[help-wanted]: https://github.com/exercism/python/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22 +[markdown-language]: https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf +[open-an-issue]: https://github.com/exercism/python/issues/new/choose +[pep8-for-humans]: https://pep8.org/ +[practice-exercise-anatomy]: https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md +[practice-exercises]: https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md +[prettier]: https://prettier.io/ +[problem-specifications]: https://github.com/exercism/problem-specifications +[python-syllabus]: https://exercism.org/tracks/python/concepts +[python-track-test-generator]: https://github.com/exercism/python/blob/main/docs/GENERATOR.md +[the-words-that-we-use]: https://github.com/exercism/docs/blob/main/community/good-member/words.md +[website-contributing-section]: https://exercism.org/docs/building From 0ab71ba34439673041a960b12dedeb1c14ebe00e Mon Sep 17 00:00:00 2001 From: BethanyG Date: Wed, 6 Oct 2021 15:10:51 -0700 Subject: [PATCH 08/31] Edits and emoji. YAY. --- CONTRIBUTING.md | 85 ++++++++++++++++++++++++++++++------------------- 1 file changed, 53 insertions(+), 32 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 61f70af74b..970cebf9bb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,16 +7,16 @@ Thank you so much for your interest in contributing to the Python track! **We a `exercsim/Python` is one of the many tracks on [exercism][exercism-website]. This repo holds all the instructions, tests, code, & support files for Python *exercises* currently under development or implemented & available for students. -Exercises are grouped into **concept** exercises which teach the [Python syllabus][python-syllabus], and **practice** exercises, which are unlocked by progressing in the syllabus tree. Practice exercises are open-ended, and can be used to practice concepts learned, try out new techniques, and _play_. These two exercise groupings can be found in the track [config.json][config-json], and under the `python/exercises` directory. +Exercises are grouped into **concept** exercises which teach the [Python syllabus][python-syllabus], and **practice** exercises, which are unlocked by progressing in the syllabus tree. Concept exercises are constrained to a small set of language or syntax features. Practice exercises are open-ended, and can be used to practice concepts learned, try out new techniques, and _play_. These two exercise groupings can be found in the track [config.json][config-json], and under the `python/exercises` directory.
## πŸ› **Did you find a bug?** -It's not uncommon that people discover typos, confusing directions, or incorrect implementations of certain tests or code examples. Or you might have a great suggestion for a hint to aid students (πŸ’™  ) , see optimizations for exemplar or test code, find some missing test cases to add, or want to correct factual and/or logical errors. Or maybe you have a great idea for an exercise or feature. +It's not uncommon that people discover typos, confusing directions, or incorrect implementations of certain tests or code examples. Or you might have a great suggestion for a hint to aid students (πŸ’™  ) , see optimizations for exemplar or test code, find missing test cases to add, or want to correct factual and/or logical errors. Or maybe you have a great idea for an exercise or feature ( β— ). _Our track is always a work in progress!_ 🌟🌟 -Please πŸ“›  [Open an issue][open-an-issue] πŸ“› , and let us know what you've found. +Please πŸ“›  [Open an issue][open-an-issue] πŸ“› , and let us know what you have found or suggest.
@@ -29,9 +29,9 @@ Please πŸ“›  [Open an issue][open-an-issue] πŸ“› , and let us know wh              3️⃣     Contributions from our [help wanted][help-wanted] issue list,              4️⃣     Larger (_and previously agreed-upon_) contributions from recent & regular (_within the last 6 months_) contributors. -When in doubt, πŸ“›  [Open an issue][open-an-issue] πŸ“›. We will happily discuss your proposed change. 🐍 +When in doubt, πŸ“›  [Open an issue][open-an-issue] πŸ“›. We will happily discuss your proposed change. 🐍 -But let's talk before you take a whole lot of time implementing anything. +But let's talk before you take a whole lot of time or energy implementing anything.
@@ -39,7 +39,7 @@ But let's talk before you take a whole lot of time implementing anything. ✨ πŸ¦„  Here is the good stuff: -[Track Structure][exercism-track-structure] **|** [Tasks][exercism-tasks] **|** [Concepts][exercism-concepts] **|** [Concept Exercises][concept-exercises] **|** [Practice Exercises][practice-exercises] **|** [Presentation][exercise-presentation] **|** [ Style Guide for Writing][exercism-writing-style] **|** [Markdown Specification][exercism-markdown-specification] +[Track Structure][exercism-track-structure] **|** [Tasks][exercism-tasks] **|** [Concepts][exercism-concepts] **|** [Concept Exercises][concept-exercises] **|** [Practice Exercises][practice-exercises] **|** [Presentation][exercise-presentation] **|** [Writing Style Guide][exercism-writing-style] **|** [Markdown Specification][exercism-markdown-specification] Web-formatted  πŸ•ΈοΈ   versions are available in the [contributing section][website-contributing-section] of exercsim.org. @@ -49,7 +49,8 @@ Web-formatted  πŸ•ΈοΈ   versions are available in the [contributing s
-🌟🌟  If you have not already done so, please take a moment to read our [Code of Conduct][exercism-code-of-conduct] & [Being a Good Community Member][being-a-good-community-member]. It might also be helpful to take a look at [The words that we use][the-words-that-we-use]. +🌟🌟  If you have not already done so, please take a moment to read our [Code of Conduct][exercism-code-of-conduct] & [Being a Good Community Member][being-a-good-community-member] documents. +It might also be helpful to take a look at [The words that we use][the-words-that-we-use]. Some defined roles in our community: [Community Member][being-a-good-community-member] **|** [Contributors][exercism-contributors] **|** [Mentors][exercism-mentors] **|** [Maintainers][exercism-track-maintainers] **|** [Admins][exercism-admins] @@ -60,67 +61,85 @@ Some defined roles in our community: [Community Member][being-a-good-community-
-- Maintainers are happy to review your work and help you out. πŸ’› πŸ’™  But they may be in a different timezone, or tied up  πŸ§Ά  with other tasks. **Please wait at least 72 hours before pinging them.** They will review your request as soon as they are able to. +- Maintainers are happy to review your work and help you. πŸ’› πŸ’™  + - They may be in a different timezone βŒš , or tied up  πŸ§Ά  with other tasks. They will review your request as soon as they are able to. + - **Please wait at least 72 hours before pinging.** - If you'd like in-progress feedback or discussion, please mark your Pull Request as a `[draft]` - Pull requests should be focused on a single exercise, issue, or change. -- Pull Request titles and descriptions should make clear **what** has changed and **why**. Please link  πŸ”—  to any related issues the PR addresses. -- πŸ“› [An issue should be opened][open-an-issue] πŸ“›  _**before**_ creating a Pull Request making significant or breaking changes to an existing exercise. - - The same holds true for changes across multiple exercises. +- Pull Request titles and descriptions should make clear **what** has changed and **why**. + - Please link  πŸ”—  to any related issues the PR addresses. +- πŸ“› [Open an issue][open-an-issue] πŸ“›   and discussed _**before**_ creating a Pull Request making significant or breaking changes to an existing exercise. + - The same rule holds true for changes across multiple exercises. - It is best to discuss changes with  πŸ§°  maintainers before doing a lot of work. -- Follow coding standards found in [PEP8][PEP8] ( ["For Humans" version here][pep8-for-humans]. We do have some more specific requirements. More on that a little later. +- Follow coding standards found in [PEP8][PEP8] (["For Humans" version here][pep8-for-humans]). + - We do have some more specific requirements. More on that a little later. - All files should have a proper [EOL][EOL] at the end. This means one carriage return at the end of the final line of text in files. - Otherwise, watch out  βš οΈ  for trailing spaces, extra blank lines, extra spaces, and spaces in blank lines. -- The CI is going to run **a lot** of checks on your PR. Pay attention to the failures, try to understand and fix them. If you need help, comment in the PR or issue.  πŸ™‹πŸ½β€β™€οΈ   The maintainers are happy to help troubleshoot. +- The CI is going to run **a lot** of checks on your PR. Pay attention to the failures, try to understand and fix them. + - If you need help, comment in the PR or issue.  πŸ™‹πŸ½β€β™€οΈ   The maintainers are happy to help troubleshoot. - βš οΈ **Before committing** βš οΈ  + βš οΈ  **Before committing** βš οΈ  -- Run `configlet fmt` and `configlet lint` before committing if [config.json](config-json) has been modified. -- Run [flake8][flake8] to ensure all Python code conforms to general style standards. +- Run `configlet fmt` and `configlet lint` if the track [config.json](config-json) has been modified. +- Run [Prettier][prettier] on all markdown files. +- Run [flake8][flake8] to ensure all Python code files conform to general code style standards. +- Run [???] to help format your code - Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly. -- If you modified or created a `hints.md` file, [regenerate the README](#generating-exercise-readmes) +- Run the `example.py` or `exemplar.py` file against the test file to ensure that it passes without error. +- If you modified or created a `hints.md` file for a practice exercise, [regenerate](#generating-exercise-readmes) it.
-## A Little More on Prose Writing Style and Standards +## πŸ“„ A Little More on Prose Writing Style and Standards
-Non-code content (_exercise introductions & instructions, hints, concept write-ups, documentation etc._) should be written in [American English][american-english]. We strive to watch [the words we use][the-words-we-use]. +Non-code content (_exercise introductions & instructions, hints, concept write-ups, documentation etc._) should be written in [American English][american-english]. We strive to watch [the words we use][the-words-that-we-use]. When a word or phrase usage is contested | ambiguous, we default to what is best understood by our international community of learners, even if it "sounds a little weird" to a "native" American English speaker. -Our documents use [Markdown][markdown-language], with certain [alterations][exercism-markdown-widgets] & [additions][exercism-internal-linking]. Here is our full [Markdown Specification][exercism-markdown-specification]. We format/lint our Markdown with [Prettier][prettier]. +Our documents use [Markdown][markdown-language], with certain [alterations][exercism-markdown-widgets] & [additions][exercism-internal-linking]. Here is our full [Markdown Specification][exercism-markdown-specification].  πŸ“ We format/lint our Markdown with [Prettier][prettier]. βœ¨
-## A Little More on Exercises +## Little More on Coding Standards +
+
+## πŸ‹οΈ A Little More on Exercises πŸ‹πŸ½β€β™€οΈ + - Each exercise must be self-contained. Please do not use or reference files that reside outside the given exercise directory. "Outside" files will not be included if a student fetches the exercise via the CLI. -- Each exercise/problem should include a complete test suite, an example/exemplar solution, and a stub file ready for student implementation. +- Each exercise/problem should include a complete test suite, an example/exemplar solution, and a stub file ready for student implementation. - See [Concept Exercise Anatomy][concept-exercise-anatomy], or [Practice Exercise Anatomy][practice-exercise-anatomy] depending on which type of exercise you are contributing to. -- For **practice exercise**, descriptions and instructions come from a centralized, cross-track [problem specifications][problem-specifications] repository. +
+ Concept Exercise Checklist> +
+ +
+ +
+ Practice Exercise Checklist> +
+ +- **Practice exercise**, descriptions and instructions come from a centralized, cross-track [problem specifications][problem-specifications] repository. - Any updates or changes need to be proposed/approved in `problem-specifications` first. - If Python-specific changes become necessary, they need to be appended to the canonical instructions by creating a `instructions.append.md` file in this (`exercism/Python`) repository. -- **Practice Exericse Test Suits** for many practice exercises are similarly [auto-generated][##Auto-Generated Test Files and Test Templates] from data in [problem specifications][problem-specifications]. +- Practice Exercise **Test Suits** for many practice exercises are similarly [auto-generated][##Auto-Generated Test Files and Test Templates] from data in [problem specifications][problem-specifications]. - Any changes to them need to be proposed/discussed in the `problem-specifications` repository and approved by **3 track maintainers**, since changes could potentially affect many (_or all_) exercism language tracks. - If Python-specific test changes become necessary, they can be appended to the exercise `tests.toml` file. πŸ“› [**Please file an issue**][open-an-issue] πŸ“›   and check with maintainers before adding any Python-specific tests.
-## Python Coding Standards - -
-
@@ -128,12 +147,14 @@ Our documents use [Markdown][markdown-language], with certain [alterations][exer
-Exercises on this track officially support Python >= `3.8` Track tooling (`test runners`, `analyzers`, and r`epresenters`) all run on Python `3.9`. +This track officially supports Python >= `3.8` The track `test runner`, `analyzer`, and `representer` run in docker on `python:3.9-slim`. + +Although the majority of test cases are written using `unittest.TestCase`, -* All exercises going forward should be written for compatibility with Python >= `3.8`,. -* Version backward _incompatibility_ (*e.g* an exercise using a `3.8` or `3.9` only feature) should be clearly notied in any exercise introduction or notes. +* All exercises should be written for compatibility with Python >= `3.8`,. +* Version backward _incompatibility_ (*e.g* an exercise using a `3.8` or `3.9` **only** feature) should be clearly noted in any exercise introduction or notes. -* _Most_ exercises will work with Python 3.6+, and _many_ are compatible with Python 2.7+. Please do not change existing exercises to add new `3.6`+ features without consulting with a maintainer first. +* _Most_ exercises will work with Python `3.6+`, and _many_ are compatible with Python 2.7+. Please do not change existing exercises to add new `3.6`+ features without consulting with a maintainer first. - All test suites and example solutions must work in all Python versions that we currently support. When in doubt about a feature, please check with maintainers. From 383ce9b7bf860438700bbcf6ea6ff9d6a120c0a0 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Tue, 5 Oct 2021 14:41:45 -0700 Subject: [PATCH 09/31] First re-write pass of contributing docs. --- CONTRIBUTING.md | 243 ++++++++++++++++++++++++------------------------ 1 file changed, 120 insertions(+), 123 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 970cebf9bb..23ca1bb274 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -Hi.  πŸ‘‹πŸ½  πŸ‘‹   +Hi.  πŸ‘‹πŸ½  πŸ‘‹   Thank you so much for your interest in contributing to the Python track! **We are happy you are here.** 🌟   πŸŽ‰ @@ -15,7 +15,7 @@ Exercises are grouped into **concept** exercises which teach the [Python syllabu It's not uncommon that people discover typos, confusing directions, or incorrect implementations of certain tests or code examples. Or you might have a great suggestion for a hint to aid students (πŸ’™  ) , see optimizations for exemplar or test code, find missing test cases to add, or want to correct factual and/or logical errors. Or maybe you have a great idea for an exercise or feature ( β— ). -_Our track is always a work in progress!_ 🌟🌟 +_Our track is always a work in progress!_ 🌟🌟 Please πŸ“›  [Open an issue][open-an-issue] πŸ“› , and let us know what you have found or suggest.
@@ -68,11 +68,11 @@ Some defined roles in our community: [Community Member][being-a-good-community- - Pull requests should be focused on a single exercise, issue, or change. - Pull Request titles and descriptions should make clear **what** has changed and **why**. - Please link  πŸ”—  to any related issues the PR addresses. -- πŸ“› [Open an issue][open-an-issue] πŸ“›   and discussed _**before**_ creating a Pull Request making significant or breaking changes to an existing exercise. +- πŸ“› [Open an issue][open-an-issue] πŸ“›   and discuss it _**before**_ creating a Pull Request making significant or breaking changes to an existing exercise. - The same rule holds true for changes across multiple exercises. - - It is best to discuss changes with  πŸ§°  maintainers before doing a lot of work. + - It is best to quickly discuss most changes with  πŸ§°  maintainers before doing a lot of work. - Follow coding standards found in [PEP8][PEP8] (["For Humans" version here][pep8-for-humans]). - - We do have some more specific requirements. More on that a little later. + - We do have some more specific requirements. More on that [a little later](a-little-more-on-coding-standards). - All files should have a proper [EOL][EOL] at the end. This means one carriage return at the end of the final line of text in files. - Otherwise, watch out  βš οΈ  for trailing spaces, extra blank lines, extra spaces, and spaces in blank lines. - The CI is going to run **a lot** of checks on your PR. Pay attention to the failures, try to understand and fix them. @@ -81,12 +81,12 @@ Some defined roles in our community: [Community Member][being-a-good-community-  βš οΈ  **Before committing** βš οΈ  -- Run `configlet fmt` and `configlet lint` if the track [config.json](config-json) has been modified. +- Run [`configlet-lint`][configlet-lint] if the track [config.json](config-json) has been modified. - Run [Prettier][prettier] on all markdown files. -- Run [flake8][flake8] to ensure all Python code files conform to general code style standards. -- Run [???] to help format your code +- Run [flake8][flake8] & [pylint][pylint] to ensure all Python code files conform to general code style standards. +- (Optionally) run [yapf][yapf] to help format your code, and give you a head start on making the linters happy. - Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly. -- Run the `example.py` or `exemplar.py` file against the test file to ensure that it passes without error. +- Run the `example.py` or `exemplar.py` file against the exercise test file to ensure that it passes without error. - If you modified or created a `hints.md` file for a practice exercise, [regenerate](#generating-exercise-readmes) it.
@@ -104,9 +104,64 @@ Our documents use [Markdown][markdown-language], with certain [alterations][exer
-## Little More on Coding Standards +## A Little More on Coding Standards
+1. We follow [PEP8][PEP8] (["For Humans" version here][pep8-for-humans]). + In particular, we (mostly) follow the [Google flavor][google-coding-style] of PEP8. +2. We use [flake8][flake8] to help us format Python code nicely. + Our `flake8` config file is [.flake8][.flake8] in the top level of this repo. +3. We use [pylint][pylint] to catch what `flake8` doesn't. + Our `pylint` config file is [pylintrc][pylintrc] in the top level of this repo. +4. We use [yapf][yapf] to auto-format our python files. + Our `.style.yapf` config file is [.style.yapf][.style.yapf] in the top level of this repo. + +If you have any questions or issues, don't hesitate to ask the maintainers -- they're always happy to help πŸ’› πŸ’™  + +Some of our code is old and does not (yet) conform to all these standards. We know it, and trust us, we're fixing it. But if you see  πŸ‘€  something,  πŸ‘„  say something. It'll motivate us to fix it! 🌈 + + +### General Code Style TL;DR: + +- _spaces_, never `Tabs` +- 4 space indentation +- 120 character per line limit (as opposed to the Google limit of 80) +- Variables, functions and methods should be `lower_case_with_underscores` (aka "snake case") +- Classes are `TitleCase` (aka "camel case") +- No single letter variable names outside of a `lambda`. This includes loop variables and comprehensions. +- Refrain from putting `list`, `tuple`, `set`, or `dict` members on their own lines. + Fit as many members as can be easily read on one line, before wrapping to a second. +- If a data structure spreads to more than one line and a break (for clarity) is needed, prefer breaking after the opening bracket. +- Avoid putting closing brackets on their own lines. Prefer closing a bracket right after the last element. +- Use `'` and not `"` as the quote character by default. +- Use `"""` for docstrings. +- Prefer [implicit line joining][implicit-line-joining] for long strings. +- Prefer enclosing imports in (), and putting each on their own line when importing multiple methods from a library. +- Two lines between `Classes`, one line between `functions`. Other vertical whitespace as needed to help readability. +- Always use an EOL to end a file. + + +### Concept Exercise Test Files + +- We have historically used [Unittest.TestCase][unittest] syntax, with [PyTest][pytest] as a test runner. +- We are transitioning to using (many) more PyTest features and syntax, but are leaving `Unittest` syntax in place where possible. +- Always check with a maintainer before introducing a PyTest feature in your tests. Not all PyTest features may be supported. +- Test **Classes** should be titled `Test`. e.g. `class CardGamesTest(unittest.TestCase):` + This is to help our test runner re-write them for display on the website. +- Test _methods_ or functions should begin with `test_`, and follow PEP8 naming. Try to make test case names descriptive but not too long. +- Favor [_parameterizing_][distinguishing-test-iterations] tests that vary only by input data. We use [unittest.TestCase.subTest][subtest] for this. An [example from Guido's Gorgeous Lasagna][guidos-gorgeous-lasagna-testfile]. A second [example from Card Games][card-games-testfile]. +- Avoid excessive line breaks or indentation - especially in parameterized tests. Excessive breaks & indentation within the `for` loops cause issues when formatting the test code for display on the website. +- Use [`enumerate()`][enumerate] where possible when looping in test cases. See [Card Games][card-games-testfile] for example usage. +- Favor using variable names like `inputs`, `data`, `input_data`, `test_data`, or `test_case_data` for test inputs. +- Favor using variable names like `results`, `expected`, `result_data`, `expected_data`, `expected_results` or `expected_outputs` for expected test outcomes. +- Favor putting the (not optional) assert failure message on it's own line outside of the `self.assert` method, and naming it `failure_msg`. See [Card Games][card-games-testfile] for example usage. +- Use `f-strings` over other methods for test failure messages. Make your messages as relevant and human-readable as possible. +- We relate the test cases for a particular task in an exercise to the **task number** via a custom [PyTest Marker][pytestmark]. These are decorators that take the form of ``@pytest.mark.task(taskno=)`. See [Guido's Gorgeous Lasagna][guidos-gorgeous-lasagna-testfile] for an example usage. +- For exercises that have large sets of data for inputs/outputs, we prefer to have **test data files**. These should be named with `_data` or `_test_data` at the end of the filename, and saved alongside the test case file. See the [Cater-Waiter][cater-waiter] exercise directory for an example of how we set this up. +- Test data files need to be added to the `editor` key within an exercises [`config.json` `files` key][exercise-config-json]. Check with a maintainer if you have questions or issues. +- For new test files going forward, omit `if __name__ == "__main__": + unittest.main()`. `Unittest` will not be able to run these files stand-alone. +- Test files should be linted with both `flake8` and `pylint`. Both are known to toss false positives for imports and unused variables in test code. Where necessary, deploy the [`#noqa`][flake8-noqa] or [`#pylint disable=`][pylint-disable-check] comments to suppress false-positive warnings. See **line 16** of [Guido's Gorgeous Lasagna][guidos-gorgeous-lasagna-testfile] test file for an example of a pylint "skip".
@@ -141,8 +196,6 @@ Our documents use [Markdown][markdown-language], with certain [alterations][exer
-
- ## Python Versions
@@ -152,9 +205,11 @@ This track officially supports Python >= `3.8` The track `test runner`, `analyz Although the majority of test cases are written using `unittest.TestCase`, * All exercises should be written for compatibility with Python >= `3.8`,. -* Version backward _incompatibility_ (*e.g* an exercise using a `3.8` or `3.9` **only** feature) should be clearly noted in any exercise introduction or notes. +* Version backward _incompatibility_ (*e.g* an exercise using a `3.8` or `3.9` **only** feature) should be clearly noted in any exercise hits, links, introductions or other notes. + +* Here is an example of how the Python documentation handles [version-tagged  πŸ· ][version-tagged-language-features] feature introduction. -* _Most_ exercises will work with Python `3.6+`, and _many_ are compatible with Python 2.7+. Please do not change existing exercises to add new `3.6`+ features without consulting with a maintainer first. +* _Most_ exercises will work with Python `3.6+`, and _many_ are compatible with Python 2.7+. Please do not change existing exercises to add new `3.6`+ features without consulting with a maintainer first. We  πŸ’› πŸ’™  modern Python, but we _also_ want to avoid student confusion when it comes to brand-new features. - All test suites and example solutions must work in all Python versions that we currently support. When in doubt about a feature, please check with maintainers. @@ -162,169 +217,96 @@ Although the majority of test cases are written using `unittest.TestCase`, ## External Libraries and Dependencies -
-
+Our tooling (_runners, analyzers and representers_) runs in isolated containers within the exercism website. Because of this, exercises cannot rely on third-party or external libraries. Any library needed for an exercise or exercise tests must be incorporated as part of the tooling build, and noted for students who are using the CLI to solve problems locally. +If your exercise depends on a third-party library (_aka not part of standard Python_), please consult with maintainers about it. We may or may not be able to accommodate the package. +
## Auto-Generated Test Files and Test Templates
-Practice exericses inherit their definitions from the [problem-specifications][problem-specifications] repository in the form of _description files_. Exercise introductions, instructions and (_in the case of **many**, but not **all**_) test files are machine-generated . +[**Practice exercises**][practice-exercise-files] inherit their definitions from the [problem-specifications][problem-specifications] repository in the form of _description files_. Exercise introductions, instructions and (_in the case of **many**, but not **all**_) test files are then machine-generated for each language track. -Changes to practice exercise _specifications_ should be raised/PR'd in [problem-specifications][problem-specifications] and approved by **3 track maintainers**. After an exercise change has gone through that process , related documents and tests for the Python track will need to be re-generated via [configlet][configlet]. Configlet is also used as part of the track CI, essential track and exercise linting, and other verification tasks. +Changes to practice exercise _specifications_ should be raised/PR'd in [problem-specifications][problem-specifications] and approved by **3 track maintainers**. After an exercise change has gone through that process , related documents and tests for the Python track will need to be [re-generated](#generating-practice-exercise-documents) via [configlet][configlet]. Configlet is also used as part of the track CI, essential track and exercise linting, and other verification tasks. -If a practice exercise has an auto-generated `_test.py` file, there will be a `.meta/template.j2` and a `.meta/tests.toml` file in the exercise directory. If an exercise implements Python track-specific tests, there may be a `.meta/additional_tests.json` to define them. These `additional_tests.json` files will automatically be included in test generation. +If a practice exercise has an auto-generated `_test.py` file, there will be a `.meta/template.j2` and a `.meta/tests.toml` file in the exercise directory. If an exercise implements Python track-specific tests, there may be a `.meta/additional_tests.json` to define them. These `additional_tests.json` files will automatically be included in test generation. -Practice exercise `_test.py` files are generated/regenerated via the [Python Track Test Generator][python-track-test-generator]. Please reach out to a maintainer if you need any help with the process. +Practice exercise `_test.py` files are generated/regenerated via the [Python Track Test Generator][python-track-test-generator]. Please reach out to a maintainer if you need any help with the process.
-## Tools and Tooling - - -################################## - - -## Architecture - -Exercism tracks inherit exercise definitions from the [problem-specifications] repository in the form of description files -(from which exercise READMEs are [generated](#generating-exercise-readmes)) - - -## Implementing an exercise - -### Exercise structure +### Python Practice Exercise structure for auto-generated tests ```Bash -exercises/[EXERCISE]/ -β”œβ”€β”€ [EXERCISE].py -β”œβ”€β”€ [EXERCISE]_test.py -β”œβ”€β”€ example.py +[/ +β”œβ”€β”€ .docs +β”‚ └── instructions.md β”œβ”€β”€ .meta +β”‚ β”œβ”€β”€ config.json +β”‚ β”œβ”€β”€ example.py β”‚ β”œβ”€β”€ template.j2 -β”‚ β”œβ”€β”€ additional_tests.json -β”‚ └── hints.md -└── README.md +β”‚ └── tests.toml +β”œβ”€β”€ .py #stub file +└── --spec-path path/to/problem/specifications ``` -#### Generating a single README +**Regenerating an Individual Exercises Documents:** ``` configlet generate --spec-path path/to/problem/specifications --only example-exercise ``` -### Implementing tests +### Implementing Practice Exercise Tests -If an unimplemented exercise has a `canonical-data.json` file in the [problem-specifications] repository, a generation template must be created. See the [test generator documentation](docs/GENERATOR.md) for more information. +If an unimplemented exercise has a `canonical-data.json` file in the [problem-specifications] repository, a generation template must be created. See the Python track [test generator documentation][python-track-test-generator] for more information. -If an unimplemented exercise does not have a `canonical-data.json` file, the test file must be written manually (use existing test files for examples). +If an unimplemented exercise does not have a `canonical-data.json` file, the test file must be written manually. -### Example solutions +### Practice Exercise Example solutions Example solution files serve two purposes: 1. Verification of the tests 2. Example implementation for mentor/student reference -### config.json - -[`config.json`](config.json) is used by the website to determine which exercises to load an in what order. It also contains some exercise metadata, such as difficulty, labels, and if the exercise is a core exercise. New entries should be places just before the first exercise that is marked `"deprecated": true`: - -```JSON - { - "slug": "current-exercise", - "uuid": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", - "core": false, - "unlocked_by": null, - "difficulty": 1, - "topics": [ - "strings" - ] - }, - <<< HERE - { - "slug": "old-exercise", - "uuid": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", - "core": false, - "unlocked_by": null, - "difficulty": 2, - "topics": null, - "status": "deprecated" - }, -``` +Unlike concept exercise, practice exercise `example.py` files are NOT intended as as a "best practice" or "standard". They are provided as proof that there is an acceptable and testable answer to the practice exercise. + -Fields - - - - - - - - - - - - - - - - - - - - - - - - - -
slugHyphenated lowercase exercise name
uuidGenerate using configlet uuid
coreSet to false; core exercises are decided by track maintainers
unlocked_bySlug for the core exercise that unlocks the new one
difficulty1 through 10. Discuss with reviewer if uncertain.
topicsArray of relevant topics from the topics list
- - -## Implementing Track-specific Exercises - -Similar to implementing a canonical exercise that has no `canonical-data.json`, but the exercise README will also need to be written manually. Carefully follow the structure of generated exercise READMEs. +## Implementing Track-specific Practice Exercises +Similar to implementing a canonical exercise that has no `canonical-data.json`, but the exercise documents will also need to be written manually. Carefully follow the structure of generated exercise documents and the [exercism practice exercise specification][practice-exercises]. +[.flake8]: https://github.com/exercism/python/blob/main/.flake8 [EOL]: https://en.wikipedia.org/wiki/Newline [PEP8]: https://www.python.org/dev/peps/pep-0008/ [american-english]: https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md [being-a-good-community-member]: https://github.com/exercism/docs/tree/main/community/good-member +[cater-waiter]: https://github.com/exercism/python/tree/main/exercises/concept/cater-waiter +[card-games-testfile]: https://github.com/exercism/python/blob/main/exercises/concept/card-games/lists_test.py [concept-exercise-anatomy]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md [concept-exercises]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md [config-json]: https://github.com/exercism/javascript/blob/main/config.json [configlet-general]: https://github.com/exercism/configlet [configlet]: https://github.com/exercism/docs/blob/main/building/configlet/generating-documents.md +[configlet-lint]: https://github.com/exercism/configlet#configlet-lint +[distinguishing-test-iterations]: https://docs.python.org/3/library/unittest.html#distinguishing-test-iterations-using-subtests +[enumerate]: https://docs.python.org/3/library/functions.html#enumerate +[exercise-config-json]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md#full-example [exercise-presentation]: https://github.com/exercism/docs/blob/main/building/tracks/presentation.md [exercism-admins]: https://github.com/exercism/docs/blob/main/community/administrators.md [exercism-code-of-conduct]: https://exercism.org/docs/using/legal/code-of-conduct @@ -340,15 +322,30 @@ Similar to implementing a canonical exercise that has no `canonical-data.json`, [exercism-website]: https://exercism.org/ [exercism-writing-style]: https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md [flake8]: http://flake8.pycqa.org/ +[flake8-noqa]: https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html#in-line-ignoring-errors +[google-coding-style]: https://google.github.io/styleguide/pyguide.html +[guidos-gorgeous-lasagna-testfile]: https://github.com/exercism/python/blob/main/exercises/concept/guidos-gorgeous-lasagna/lasagna_test.py [help-wanted]: https://github.com/exercism/python/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22 +[implicit-line-joining]: https://google.github.io/styleguide/pyguide.html#32-line-length [markdown-language]: https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf [open-an-issue]: https://github.com/exercism/python/issues/new/choose [pep8-for-humans]: https://pep8.org/ [practice-exercise-anatomy]: https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md +[practice-exercise-files]: https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md#exercise-files [practice-exercises]: https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md [prettier]: https://prettier.io/ [problem-specifications]: https://github.com/exercism/problem-specifications +[pylint]: https://pylint.pycqa.org/en/v2.11.1/user_guide/index.html +[pylintrc]: https://github.com/exercism/python/blob/main/pylintrc +[pylint-disable-check]: https://pylint.pycqa.org/en/latest/user_guide/message-control.html#block-disables +[pytest]: https://docs.pytest.org/en/6.2.x/contents.html +[pytestmark]: https://docs.pytest.org/en/6.2.x/example/markers.html [python-syllabus]: https://exercism.org/tracks/python/concepts [python-track-test-generator]: https://github.com/exercism/python/blob/main/docs/GENERATOR.md +[.style.yapf]: https://github.com/exercism/python/blob/main/.style.yapf +[subtest]: https://docs.python.org/3/library/unittest.html#unittest.TestCase.subTest [the-words-that-we-use]: https://github.com/exercism/docs/blob/main/community/good-member/words.md +[unittest]: https://docs.python.org/3/library/unittest.html#unittest.TestCase +[version-tagged-language-features]: https://docs.python.org/3/library/stdtypes.html#dict.popitem [website-contributing-section]: https://exercism.org/docs/building +[yapf]: https://github.com/google/yapf From a942f675d79a16c21b978b311e1882b8ed946238 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Thu, 14 Oct 2021 09:56:15 -0700 Subject: [PATCH 10/31] Experiment with checklist --- CONTRIBUTING.md | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 23ca1bb274..a726a0b698 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,6 +7,10 @@ Thank you so much for your interest in contributing to the Python track! **We a `exercsim/Python` is one of the many tracks on [exercism][exercism-website]. This repo holds all the instructions, tests, code, & support files for Python *exercises* currently under development or implemented & available for students. +βš’ This track's exercises support Python `3.8`. + +βš’ Track tooling (_test runner_,_represter_, and _analyzer_, _CI_) runs on Python `3.9`. + Exercises are grouped into **concept** exercises which teach the [Python syllabus][python-syllabus], and **practice** exercises, which are unlocked by progressing in the syllabus tree. Concept exercises are constrained to a small set of language or syntax features. Practice exercises are open-ended, and can be used to practice concepts learned, try out new techniques, and _play_. These two exercise groupings can be found in the track [config.json][config-json], and under the `python/exercises` directory.
@@ -16,7 +20,7 @@ Exercises are grouped into **concept** exercises which teach the [Python syllabu It's not uncommon that people discover typos, confusing directions, or incorrect implementations of certain tests or code examples. Or you might have a great suggestion for a hint to aid students (πŸ’™  ) , see optimizations for exemplar or test code, find missing test cases to add, or want to correct factual and/or logical errors. Or maybe you have a great idea for an exercise or feature ( β— ). _Our track is always a work in progress!_ 🌟🌟 -Please πŸ“›  [Open an issue][open-an-issue] πŸ“› , and let us know what you have found or suggest. +Please πŸ“› [Open an issue][open-an-issue] πŸ“›, and let us know what you have found or suggest.
@@ -29,7 +33,7 @@ Please πŸ“›  [Open an issue][open-an-issue] πŸ“› , and let us know wh              3️⃣     Contributions from our [help wanted][help-wanted] issue list,              4️⃣     Larger (_and previously agreed-upon_) contributions from recent & regular (_within the last 6 months_) contributors. -When in doubt, πŸ“›  [Open an issue][open-an-issue] πŸ“›. We will happily discuss your proposed change. 🐍 +When in doubt,  πŸ“› [Open an issue][open-an-issue] πŸ“› . We will happily discuss your proposed change. 🐍 But let's talk before you take a whole lot of time or energy implementing anything. @@ -81,13 +85,22 @@ Some defined roles in our community: [Community Member][being-a-good-community-  βš οΈ  **Before committing** βš οΈ  -- Run [`configlet-lint`][configlet-lint] if the track [config.json](config-json) has been modified. -- Run [Prettier][prettier] on all markdown files. -- Run [flake8][flake8] & [pylint][pylint] to ensure all Python code files conform to general code style standards. -- (Optionally) run [yapf][yapf] to help format your code, and give you a head start on making the linters happy. -- Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly. -- Run the `example.py` or `exemplar.py` file against the exercise test file to ensure that it passes without error. -- If you modified or created a `hints.md` file for a practice exercise, [regenerate](#generating-exercise-readmes) it. +
+  βš οΈ  Before committing βš οΈ  + +- [ ] Run [`configlet-lint`][configlet-lint] if the track [config.json](config-json) has been modified. +- [ ] Run [Prettier][prettier] on all markdown files. +- [ ] Run [flake8][flake8] & [pylint][pylint] to ensure all Python code files conform to general code style standards. +- [ ] (Optionally) run [yapf][yapf] to help format your code, and give you a head start on making the linters happy. +- [ ] Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly. +- [ ] Run the `example.py` or `exemplar.py` file against the exercise test file to ensure that it passes without error. +- [ ] If you modified or created a `hints.md` file for a practice exercise, [regenerate](#generating-exercise-readmes) it. + +
+ +
+ +
@@ -200,16 +213,16 @@ Some of our code is old and does not (yet) conform to all these standards. We k
-This track officially supports Python >= `3.8` The track `test runner`, `analyzer`, and `representer` run in docker on `python:3.9-slim`. +This track officially supports Python = `3.8` The track `test runner`, `analyzer`, and `representer` run in docker on `python:3.9-slim`. Although the majority of test cases are written using `unittest.TestCase`, -* All exercises should be written for compatibility with Python >= `3.8`,. +* All exercises should be written for compatibility with Python = `3.8` or `3.9`. * Version backward _incompatibility_ (*e.g* an exercise using a `3.8` or `3.9` **only** feature) should be clearly noted in any exercise hits, links, introductions or other notes. * Here is an example of how the Python documentation handles [version-tagged  πŸ· ][version-tagged-language-features] feature introduction. -* _Most_ exercises will work with Python `3.6+`, and _many_ are compatible with Python 2.7+. Please do not change existing exercises to add new `3.6`+ features without consulting with a maintainer first. We  πŸ’› πŸ’™  modern Python, but we _also_ want to avoid student confusion when it comes to brand-new features. +* _Most_ exercises will work with Python `3.6+`, and _many_ are compatible with Python `2.7+`. Please do not change existing exercises to add new language features without consulting with a maintainer first. We  πŸ’› πŸ’™  modern Python, but we _also_ want to avoid student confusion when it comes to which Python versions support brand-new features. - All test suites and example solutions must work in all Python versions that we currently support. When in doubt about a feature, please check with maintainers. From 672e58b52c260cdec9c1b6ef1b20a25cf8d1b427 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Thu, 14 Oct 2021 15:24:01 -0700 Subject: [PATCH 11/31] More formatting and spelling and images. --- CONTRIBUTING.md | 94 ++++++++++++++++++++++++++++++------------------- 1 file changed, 58 insertions(+), 36 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a726a0b698..d92fb7ddd1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,15 +1,20 @@ -# Contributing +
-Hi.  πŸ‘‹πŸ½  πŸ‘‹   + +

Contributing

-Thank you so much for your interest in contributing to the Python track! **We are happy you are here.** 🌟   πŸŽ‰ +
+
+Hi.  πŸ‘‹πŸ½  πŸ‘‹   **We are happy you are here.**  πŸŽ‰πŸŒŸ -`exercsim/Python` is one of the many tracks on [exercism][exercism-website]. This repo holds all the instructions, tests, code, & support files for Python *exercises* currently under development or implemented & available for students. +Thank you so much for your interest in contributing! -βš’ This track's exercises support Python `3.8`. +**`exercsim/Python`** is one of many programming language tracks on [exercism(dot)org][exercism-website]. +This repo holds all the instructions, tests, code, & support files for Python *exercises* currently under development or implemented & available for students. -βš’ Track tooling (_test runner_,_represter_, and _analyzer_, _CI_) runs on Python `3.9`. + 🌟   Track exercises support Python `3.8`. + 🌟   Track tooling (_test runner_,_represter_, and _analyzer_, _CI_) runs on Python `3.9`. Exercises are grouped into **concept** exercises which teach the [Python syllabus][python-syllabus], and **practice** exercises, which are unlocked by progressing in the syllabus tree. Concept exercises are constrained to a small set of language or syntax features. Practice exercises are open-ended, and can be used to practice concepts learned, try out new techniques, and _play_. These two exercise groupings can be found in the track [config.json][config-json], and under the `python/exercises` directory. @@ -17,10 +22,10 @@ Exercises are grouped into **concept** exercises which teach the [Python syllabu ## πŸ› **Did you find a bug?** -It's not uncommon that people discover typos, confusing directions, or incorrect implementations of certain tests or code examples. Or you might have a great suggestion for a hint to aid students (πŸ’™  ) , see optimizations for exemplar or test code, find missing test cases to add, or want to correct factual and/or logical errors. Or maybe you have a great idea for an exercise or feature ( β— ). +It is not uncommon to discover typos, confusing directions, or incorrect implementations of certain tests or code examples. Or you might have a great suggestion for a hint to aid students ( πŸ’™  ), see optimizations for exemplar or test code, find missing test cases to add, or want to correct factual and/or logical errors. Or maybe you have a great idea for an exercise or feature (❗ ). _Our track is always a work in progress!_ 🌟🌟 -Please πŸ“› [Open an issue][open-an-issue] πŸ“›, and let us know what you have found or suggest. +Please πŸ“› [ Open an issue ][open-an-issue]πŸ“› , and let us know what you have found/suggest.
@@ -33,9 +38,8 @@ Please πŸ“› [Open an issue][open-an-issue] πŸ“›, and let us know              3️⃣     Contributions from our [help wanted][help-wanted] issue list,              4️⃣     Larger (_and previously agreed-upon_) contributions from recent & regular (_within the last 6 months_) contributors. -When in doubt,  πŸ“› [Open an issue][open-an-issue] πŸ“› . We will happily discuss your proposed change. 🐍 - -But let's talk before you take a whole lot of time or energy implementing anything. +When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We will happily discuss your proposed change. +🐍  _But we should talk before you take a whole lot of time or energy implementing anything._
@@ -43,7 +47,7 @@ But let's talk before you take a whole lot of time or energy implementing anythi ✨ πŸ¦„  Here is the good stuff: -[Track Structure][exercism-track-structure] **|** [Tasks][exercism-tasks] **|** [Concepts][exercism-concepts] **|** [Concept Exercises][concept-exercises] **|** [Practice Exercises][practice-exercises] **|** [Presentation][exercise-presentation] **|** [Writing Style Guide][exercism-writing-style] **|** [Markdown Specification][exercism-markdown-specification] +[Structure][exercism-track-structure] **|** [Tasks][exercism-tasks] **|** [Concepts][exercism-concepts] **|** [Concept Exercises][concept-exercises] **|** [Practice Exercises][practice-exercises] **|** [Presentation][exercise-presentation] **|** [Writing Style Guide][exercism-writing-style] **|** [Markdown Specification][exercism-markdown-specification] Web-formatted  πŸ•ΈοΈ   versions are available in the [contributing section][website-contributing-section] of exercsim.org. @@ -57,7 +61,7 @@ Web-formatted  πŸ•ΈοΈ   versions are available in the [contributing s It might also be helpful to take a look at [The words that we use][the-words-that-we-use]. -Some defined roles in our community: [Community Member][being-a-good-community-member] **|** [Contributors][exercism-contributors] **|** [Mentors][exercism-mentors] **|** [Maintainers][exercism-track-maintainers] **|** [Admins][exercism-admins] +Some defined roles in our community: [Contributors][exercism-contributors] **|** [Mentors][exercism-mentors] **|** [Maintainers][exercism-track-maintainers] **|** [Admins][exercism-admins]
@@ -72,7 +76,7 @@ Some defined roles in our community: [Community Member][being-a-good-community- - Pull requests should be focused on a single exercise, issue, or change. - Pull Request titles and descriptions should make clear **what** has changed and **why**. - Please link  πŸ”—  to any related issues the PR addresses. -- πŸ“› [Open an issue][open-an-issue] πŸ“›   and discuss it _**before**_ creating a Pull Request making significant or breaking changes to an existing exercise. +- πŸ“› [ Open an issue ][open-an-issue]πŸ“› and discuss it _**before**_ creating a Pull Request making significant or breaking changes to an existing exercise. - The same rule holds true for changes across multiple exercises. - It is best to quickly discuss most changes with  πŸ§°  maintainers before doing a lot of work. - Follow coding standards found in [PEP8][PEP8] (["For Humans" version here][pep8-for-humans]). @@ -83,24 +87,41 @@ Some defined roles in our community: [Community Member][being-a-good-community- - If you need help, comment in the PR or issue.  πŸ™‹πŸ½β€β™€οΈ   The maintainers are happy to help troubleshoot. - βš οΈ  **Before committing** βš οΈ  +⚠️  Before committing βš οΈ
-  βš οΈ  Before committing βš οΈ  +  βš οΈ  Before committing βš οΈ  + +- [βœ”] Run [`configlet-lint`][configlet-lint] if the track [config.json](config-json) has been modified. +- [βœ”] Run [Prettier][prettier] on all markdown files. +- [βœ”] Run [flake8][flake8] & [pylint][pylint] to ensure all Python code files conform to general code style standards. +- [ ] (_Optionally_) run [yapf][yapf] to help format your code, and give you a head start on making the linters happy. +- [βœ”] Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly. +- [βœ”] Run the `example.py` or `exemplar.py` file against the exercise test file to ensure that it passes without error. +- [βœ”] If you modified or created a `hints.md` file for a practice exercise, [regenerate](#generating-exercise-readmes) it. -- [ ] Run [`configlet-lint`][configlet-lint] if the track [config.json](config-json) has been modified. -- [ ] Run [Prettier][prettier] on all markdown files. -- [ ] Run [flake8][flake8] & [pylint][pylint] to ensure all Python code files conform to general code style standards. -- [ ] (Optionally) run [yapf][yapf] to help format your code, and give you a head start on making the linters happy. -- [ ] Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly. -- [ ] Run the `example.py` or `exemplar.py` file against the exercise test file to ensure that it passes without error. -- [ ] If you modified or created a `hints.md` file for a practice exercise, [regenerate](#generating-exercise-readmes) it.

+⚠️  Before committing βš οΈ + +
+ Pre-Commit Checklist + +1. Run [`configlet-lint`][configlet-lint] if the track [config.json](config-json) has been modified. +2. Run [Prettier][prettier] on all markdown files. + - (_Optionally_) run [yapf][yapf] to help format your code, and give you a head start on making the linters happy. +3. Run [flake8][flake8] & [pylint][pylint] to ensure all Python code files conform to general code style standards. +4. Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly. +5. Run the `example.py` or `exemplar.py` file against the exercise test file to ensure that it passes without error. +6. If you modified or created a `hints.md` file for a practice exercise, [regenerate](#generating-exercise-readmes) it. +
+
+ +
@@ -136,22 +157,22 @@ Some of our code is old and does not (yet) conform to all these standards. We k ### General Code Style TL;DR: -- _spaces_, never `Tabs` -- 4 space indentation -- 120 character per line limit (as opposed to the Google limit of 80) -- Variables, functions and methods should be `lower_case_with_underscores` (aka "snake case") -- Classes are `TitleCase` (aka "camel case") -- No single letter variable names outside of a `lambda`. This includes loop variables and comprehensions. +- _**spaces**_, never `Tabs` +- **4 space** indentation +- **120 character per line limit** (_as opposed to the Google limit of 79_) +- Variable, function, and method names should be `lower_case_with_underscores` (_aka "snake case"_) +- Classes should be named in `TitleCase` (_aka "camel case"_) +- **No single letter variable names** outside of a `lambda`. This includes loop variables and comprehensions. - Refrain from putting `list`, `tuple`, `set`, or `dict` members on their own lines. - Fit as many members as can be easily read on one line, before wrapping to a second. -- If a data structure spreads to more than one line and a break (for clarity) is needed, prefer breaking after the opening bracket. + Fit as many data members as can be easily read on one line, before wrapping to a second. +- If a data structure spreads to more than one line and a break (_for clarity_) is needed, prefer breaking after the opening bracket. - Avoid putting closing brackets on their own lines. Prefer closing a bracket right after the last element. -- Use `'` and not `"` as the quote character by default. -- Use `"""` for docstrings. +- Use **`'`** and not **`"`** as the quote character by default. +- Use **`"""`** for docstrings. - Prefer [implicit line joining][implicit-line-joining] for long strings. -- Prefer enclosing imports in (), and putting each on their own line when importing multiple methods from a library. +- Prefer enclosing imports in **`()`**, and putting each on their own line when importing multiple methods. - Two lines between `Classes`, one line between `functions`. Other vertical whitespace as needed to help readability. -- Always use an EOL to end a file. +- Always use an **`EOL`** to end a file. ### Concept Exercise Test Files @@ -203,7 +224,8 @@ Some of our code is old and does not (yet) conform to all these standards. We k - Practice Exercise **Test Suits** for many practice exercises are similarly [auto-generated][##Auto-Generated Test Files and Test Templates] from data in [problem specifications][problem-specifications]. - Any changes to them need to be proposed/discussed in the `problem-specifications` repository and approved by **3 track maintainers**, since changes could potentially affect many (_or all_) exercism language tracks. - - If Python-specific test changes become necessary, they can be appended to the exercise `tests.toml` file. πŸ“› [**Please file an issue**][open-an-issue] πŸ“›   and check with maintainers before adding any Python-specific tests. + - If Python-specific test changes become necessary, they can be appended to the exercise `tests.toml` file. + - πŸ“› [ **Please file an issue**][open-an-issue] πŸ“›  and check with maintainers before adding any Python-specific tests.
From 63aed69c58d393f6a95520de419ba52d7dfecc1b Mon Sep 17 00:00:00 2001 From: BethanyG Date: Thu, 14 Oct 2021 15:28:19 -0700 Subject: [PATCH 12/31] More formatting and spelling and images. --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d92fb7ddd1..c83ef3e67b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,9 +14,9 @@ Thank you so much for your interest in contributing! This repo holds all the instructions, tests, code, & support files for Python *exercises* currently under development or implemented & available for students. 🌟   Track exercises support Python `3.8`. - 🌟   Track tooling (_test runner_,_represter_, and _analyzer_, _CI_) runs on Python `3.9`. + 🌟   Track tooling (_test-runner, representer, analyzer, and Continuous Integration_) runs on Python `3.9`. -Exercises are grouped into **concept** exercises which teach the [Python syllabus][python-syllabus], and **practice** exercises, which are unlocked by progressing in the syllabus tree. Concept exercises are constrained to a small set of language or syntax features. Practice exercises are open-ended, and can be used to practice concepts learned, try out new techniques, and _play_. These two exercise groupings can be found in the track [config.json][config-json], and under the `python/exercises` directory. +Exercises are grouped into **concept** exercises which teach the [Python syllabus][python-syllabus], and **practice** exercises, which are unlocked by progressing in the syllabus tree  πŸŒ΄  . Concept exercises are constrained to a small set of language or syntax features. Practice exercises are open-ended, and can be used to practice concepts learned, try out new techniques, and _play_. These two exercise groupings can be found in the track [config.json][config-json], and under the `python/exercises` directory.
From 81ed309a2da142343ab2149b3cb84de5e1967aef Mon Sep 17 00:00:00 2001 From: BethanyG Date: Thu, 14 Oct 2021 16:08:57 -0700 Subject: [PATCH 13/31] More formatting and spelling and images. --- CONTRIBUTING.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c83ef3e67b..b076ad52fb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,6 +20,22 @@ Exercises are grouped into **concept** exercises which teach the [Python syllabu
+ + +🌟🌟  If you have not already done so, please take a moment to read [Code of Conduct][exercism-code-of-conduct]. πŸŒŸπŸŒŸ  +It might also be helpful to look at [Being a Good Community Member][being-a-good-community-member] & [The words that we use][the-words-that-we-use]. + +Some defined roles in our community: [Contributors][exercism-contributors] **|** [Mentors][exercism-mentors] **|** [Maintainers][exercism-track-maintainers] **|** [Admins][exercism-admins] + +
+ + +✨ πŸ¦„  _**Want to jump directly into Exercism specifications & detail?**_ +     [Structure][exercism-track-structure] **|** [Tasks][exercism-tasks] **|** [Concepts][exercism-concepts] **|** [Concept Exercises][concept-exercises] **|** [Practice Exercises][practice-exercises] **|** [Presentation][exercise-presentation] +     [Writing Style Guide][exercism-writing-style] **|** [Markdown Specification][exercism-markdown-specification] (_ βœ¨   versions available in [contributing][website-contributing-section] on [exercism(dot)org][exercism-website]._) + +
+ ## πŸ› **Did you find a bug?** It is not uncommon to discover typos, confusing directions, or incorrect implementations of certain tests or code examples. Or you might have a great suggestion for a hint to aid students ( πŸ’™  ), see optimizations for exemplar or test code, find missing test cases to add, or want to correct factual and/or logical errors. Or maybe you have a great idea for an exercise or feature (❗ ). @@ -76,7 +92,7 @@ Some defined roles in our community: [Contributors][exercism-contributors] **|* - Pull requests should be focused on a single exercise, issue, or change. - Pull Request titles and descriptions should make clear **what** has changed and **why**. - Please link  πŸ”—  to any related issues the PR addresses. -- πŸ“› [ Open an issue ][open-an-issue]πŸ“› and discuss it _**before**_ creating a Pull Request making significant or breaking changes to an existing exercise. +- πŸ“› [ Open an issue ][open-an-issue]πŸ“›  and discuss it _**before**_ creating a Pull Request making significant or breaking changes to an existing exercise. - The same rule holds true for changes across multiple exercises. - It is best to quickly discuss most changes with  πŸ§°  maintainers before doing a lot of work. - Follow coding standards found in [PEP8][PEP8] (["For Humans" version here][pep8-for-humans]). From 05c6afa22e60d0804306ff5b90708339844b413a Mon Sep 17 00:00:00 2001 From: BethanyG Date: Thu, 14 Oct 2021 16:20:27 -0700 Subject: [PATCH 14/31] More formatting and spelling and images. --- CONTRIBUTING.md | 70 +++++++++---------------------------------------- 1 file changed, 12 insertions(+), 58 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b076ad52fb..fbe1c06e6e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,7 +22,7 @@ Exercises are grouped into **concept** exercises which teach the [Python syllabu -🌟🌟  If you have not already done so, please take a moment to read [Code of Conduct][exercism-code-of-conduct]. πŸŒŸπŸŒŸ  +🌟🌟  If you have not already done so, please take a moment to read our [Code of Conduct][exercism-code-of-conduct]. πŸŒŸπŸŒŸ  It might also be helpful to look at [Being a Good Community Member][being-a-good-community-member] & [The words that we use][the-words-that-we-use]. Some defined roles in our community: [Contributors][exercism-contributors] **|** [Mentors][exercism-mentors] **|** [Maintainers][exercism-track-maintainers] **|** [Admins][exercism-admins] @@ -59,73 +59,30 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil
-## :books: **Want to jump directly into Exercism specifications & detail?** - -✨ πŸ¦„  Here is the good stuff: - -[Structure][exercism-track-structure] **|** [Tasks][exercism-tasks] **|** [Concepts][exercism-concepts] **|** [Concept Exercises][concept-exercises] **|** [Practice Exercises][practice-exercises] **|** [Presentation][exercise-presentation] **|** [Writing Style Guide][exercism-writing-style] **|** [Markdown Specification][exercism-markdown-specification] - -Web-formatted  πŸ•ΈοΈ   versions are available in the [contributing section][website-contributing-section] of exercsim.org. - -
- -## 🌍   The Exercism Community   🌏 - -
- -🌟🌟  If you have not already done so, please take a moment to read our [Code of Conduct][exercism-code-of-conduct] & [Being a Good Community Member][being-a-good-community-member] documents. -It might also be helpful to take a look at [The words that we use][the-words-that-we-use]. - - -Some defined roles in our community: [Contributors][exercism-contributors] **|** [Mentors][exercism-mentors] **|** [Maintainers][exercism-track-maintainers] **|** [Admins][exercism-admins] - -
- ## In General
- Maintainers are happy to review your work and help you. πŸ’› πŸ’™  - - They may be in a different timezone βŒš , or tied up  πŸ§Ά  with other tasks. They will review your request as soon as they are able to. + - They may be in a different timezone βŒš , or tied up  πŸ§Ά  with other tasks. + - Maintainers will review your request as soon as they are able to. - **Please wait at least 72 hours before pinging.** -- If you'd like in-progress feedback or discussion, please mark your Pull Request as a `[draft]` -- Pull requests should be focused on a single exercise, issue, or change. +- If you'd like in-progress feedback or discussion, please mark your Pull Request as a **`[draft]`** +- Pull requests should be focused around a single exercise, issue, or change. - Pull Request titles and descriptions should make clear **what** has changed and **why**. - Please link  πŸ”—  to any related issues the PR addresses. -- πŸ“› [ Open an issue ][open-an-issue]πŸ“›  and discuss it _**before**_ creating a Pull Request making significant or breaking changes to an existing exercise. - - The same rule holds true for changes across multiple exercises. - - It is best to quickly discuss most changes with  πŸ§°  maintainers before doing a lot of work. +- πŸ“› [ Open an issue ][open-an-issue]πŸ“›  and discuss it with  πŸ§°  maintainers _**before**_: + - creating a Pull Request making significant or breaking changes. + - for changes across multiple exercises, even if they are typos or small. + - anything that is going to require doing a lot of work (_on your part or the maintainers part_). - Follow coding standards found in [PEP8][PEP8] (["For Humans" version here][pep8-for-humans]). - - We do have some more specific requirements. More on that [a little later](a-little-more-on-coding-standards). - All files should have a proper [EOL][EOL] at the end. This means one carriage return at the end of the final line of text in files. - Otherwise, watch out  βš οΈ  for trailing spaces, extra blank lines, extra spaces, and spaces in blank lines. -- The CI is going to run **a lot** of checks on your PR. Pay attention to the failures, try to understand and fix them. - - If you need help, comment in the PR or issue.  πŸ™‹πŸ½β€β™€οΈ   The maintainers are happy to help troubleshoot. - - -⚠️  Before committing βš οΈ +- Continuous Integration is going to run **a lot** of checks on your PR. Pay attention to the failures, try to understand and fix them. +- If you need help, comment in the PR or issue.  πŸ™‹πŸ½β€β™€οΈ   The maintainers are happy to help troubleshoot.
-  βš οΈ  Before committing βš οΈ  - -- [βœ”] Run [`configlet-lint`][configlet-lint] if the track [config.json](config-json) has been modified. -- [βœ”] Run [Prettier][prettier] on all markdown files. -- [βœ”] Run [flake8][flake8] & [pylint][pylint] to ensure all Python code files conform to general code style standards. -- [ ] (_Optionally_) run [yapf][yapf] to help format your code, and give you a head start on making the linters happy. -- [βœ”] Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly. -- [βœ”] Run the `example.py` or `exemplar.py` file against the exercise test file to ensure that it passes without error. -- [βœ”] If you modified or created a `hints.md` file for a practice exercise, [regenerate](#generating-exercise-readmes) it. - - -
- -
- - -⚠️  Before committing βš οΈ - -
- Pre-Commit Checklist + ⚠️  Pre-Commit Checklist βš οΈ 1. Run [`configlet-lint`][configlet-lint] if the track [config.json](config-json) has been modified. 2. Run [Prettier][prettier] on all markdown files. @@ -138,9 +95,6 @@ Some defined roles in our community: [Contributors][exercism-contributors] **|*
- -
- ## πŸ“„ A Little More on Prose Writing Style and Standards
From 8105e51173a5036c1c81a5794b636ef771e630e5 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Thu, 14 Oct 2021 16:21:43 -0700 Subject: [PATCH 15/31] More formatting and spelling and images. --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fbe1c06e6e..1817bd3fbd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,6 +81,7 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil - Continuous Integration is going to run **a lot** of checks on your PR. Pay attention to the failures, try to understand and fix them. - If you need help, comment in the PR or issue.  πŸ™‹πŸ½β€β™€οΈ   The maintainers are happy to help troubleshoot. +
⚠️  Pre-Commit Checklist βš οΈ From a54efd3ae100d9f5b4a848208ebf42b50f641cf0 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Thu, 14 Oct 2021 16:23:40 -0700 Subject: [PATCH 16/31] More formatting and spelling and images. --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1817bd3fbd..a3d768854b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -76,9 +76,9 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil - for changes across multiple exercises, even if they are typos or small. - anything that is going to require doing a lot of work (_on your part or the maintainers part_). - Follow coding standards found in [PEP8][PEP8] (["For Humans" version here][pep8-for-humans]). -- All files should have a proper [EOL][EOL] at the end. This means one carriage return at the end of the final line of text in files. +- All files should have a proper [EOL][EOL] at the end. This means one carriage return at the end of the final line. - Otherwise, watch out  βš οΈ  for trailing spaces, extra blank lines, extra spaces, and spaces in blank lines. -- Continuous Integration is going to run **a lot** of checks on your PR. Pay attention to the failures, try to understand and fix them. +- Continuous Integration is going to run **a lot** of checks. Pay attention to failures & try to understand and fix them. - If you need help, comment in the PR or issue.  πŸ™‹πŸ½β€β™€οΈ   The maintainers are happy to help troubleshoot. @@ -92,6 +92,7 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil 4. Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly. 5. Run the `example.py` or `exemplar.py` file against the exercise test file to ensure that it passes without error. 6. If you modified or created a `hints.md` file for a practice exercise, [regenerate](#generating-exercise-readmes) it. +

From 339361e5f5ebd55b12144b804295bd0671986d0f Mon Sep 17 00:00:00 2001 From: BethanyG Date: Thu, 14 Oct 2021 16:28:57 -0700 Subject: [PATCH 17/31] More formatting and spelling and images. --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a3d768854b..8d9293a46d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -76,11 +76,12 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil - for changes across multiple exercises, even if they are typos or small. - anything that is going to require doing a lot of work (_on your part or the maintainers part_). - Follow coding standards found in [PEP8][PEP8] (["For Humans" version here][pep8-for-humans]). -- All files should have a proper [EOL][EOL] at the end. This means one carriage return at the end of the final line. +- All files should have a proper [EOL][EOL]. This means one carriage return at the end of the final line of text files. - Otherwise, watch out  βš οΈ  for trailing spaces, extra blank lines, extra spaces, and spaces in blank lines. - Continuous Integration is going to run **a lot** of checks. Pay attention to failures & try to understand and fix them. -- If you need help, comment in the PR or issue.  πŸ™‹πŸ½β€β™€οΈ   The maintainers are happy to help troubleshoot. +- If you need help, comment in the PR or issue.  πŸ™‹πŸ½β€β™€οΈ   The maintainers are happy to help troubleshoot. +
⚠️  Pre-Commit Checklist βš οΈ From bba62fcbc2fff7b29bd30031cec4e64cefb34f50 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Thu, 14 Oct 2021 17:00:08 -0700 Subject: [PATCH 18/31] More formatting and spelling and images. --- CONTRIBUTING.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8d9293a46d..8728bb52e3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,8 +64,8 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil
- Maintainers are happy to review your work and help you. πŸ’› πŸ’™  - - They may be in a different timezone βŒš , or tied up  πŸ§Ά  with other tasks. - Maintainers will review your request as soon as they are able to. + - **BUT** They may be in a different timezone βŒš , or tied up  πŸ§Ά  with other tasks. - **Please wait at least 72 hours before pinging.** - If you'd like in-progress feedback or discussion, please mark your Pull Request as a **`[draft]`** - Pull requests should be focused around a single exercise, issue, or change. @@ -85,14 +85,15 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil
⚠️  Pre-Commit Checklist βš οΈ +
-1. Run [`configlet-lint`][configlet-lint] if the track [config.json](config-json) has been modified. -2. Run [Prettier][prettier] on all markdown files. - - (_Optionally_) run [yapf][yapf] to help format your code, and give you a head start on making the linters happy. -3. Run [flake8][flake8] & [pylint][pylint] to ensure all Python code files conform to general code style standards. -4. Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly. -5. Run the `example.py` or `exemplar.py` file against the exercise test file to ensure that it passes without error. -6. If you modified or created a `hints.md` file for a practice exercise, [regenerate](#generating-exercise-readmes) it. + 1.  Run [`configlet-lint`][configlet-lint] if the track [config.json](config-json) has been modified. + 2.  Run [Prettier][prettier] on all markdown files. + - (_Optionally_) run [yapf][yapf] to help format your code, and give you a head start on making the linters happy. + 3.  Run [flake8][flake8] & [pylint][pylint] to ensure all Python code files conform to general code style standards. + 4.  Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly. + 5.  Run the `example.py` or `exemplar.py` file against the exercise test file to ensure that it passes without error. + 6.  If you modified or created a `hints.md` file for a practice exercise, [regenerate](#generating-practice-exercise-documents) it.

@@ -104,7 +105,7 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil Non-code content (_exercise introductions & instructions, hints, concept write-ups, documentation etc._) should be written in [American English][american-english]. We strive to watch [the words we use][the-words-that-we-use]. -When a word or phrase usage is contested | ambiguous, we default to what is best understood by our international community of learners, even if it "sounds a little weird" to a "native" American English speaker. +When a word or phrase usage is contested/ambiguous, we default to what is best understood by our international community of learners, even if it "sounds a little weird" to a "native" American English speaker. Our documents use [Markdown][markdown-language], with certain [alterations][exercism-markdown-widgets] & [additions][exercism-internal-linking]. Here is our full [Markdown Specification][exercism-markdown-specification].  πŸ“ We format/lint our Markdown with [Prettier][prettier]. βœ¨ @@ -210,8 +211,6 @@ Some of our code is old and does not (yet) conform to all these standards. We k This track officially supports Python = `3.8` The track `test runner`, `analyzer`, and `representer` run in docker on `python:3.9-slim`. -Although the majority of test cases are written using `unittest.TestCase`, - * All exercises should be written for compatibility with Python = `3.8` or `3.9`. * Version backward _incompatibility_ (*e.g* an exercise using a `3.8` or `3.9` **only** feature) should be clearly noted in any exercise hits, links, introductions or other notes. From 8f6ee14a5302a471f3a735618fff5393f46f4e67 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Thu, 14 Oct 2021 17:25:01 -0700 Subject: [PATCH 19/31] More formatting and spelling and images. --- CONTRIBUTING.md | 94 ++++++++++++++++++++++++++++++------------------- 1 file changed, 57 insertions(+), 37 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8728bb52e3..9f7061e144 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,12 +63,13 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil
-- Maintainers are happy to review your work and help you. πŸ’› πŸ’™  - - Maintainers will review your request as soon as they are able to. - - **BUT** They may be in a different timezone βŒš , or tied up  πŸ§Ά  with other tasks. +- Maintainers are happy to review your work and help troubleshoot with you. πŸ’› πŸ’™  + - Requests are reviewed as soon as is practical/possible. + - (❗ ) Reviewers may be in a different timezone βŒš , or tied up  πŸ§Ά  with other tasks. - **Please wait at least 72 hours before pinging.** -- If you'd like in-progress feedback or discussion, please mark your Pull Request as a **`[draft]`** -- Pull requests should be focused around a single exercise, issue, or change. +- If you need help, comment in the Pull Request/issue.  πŸ™‹πŸ½β€β™€οΈ   +- If you would like in-progress feedback/discussion, please mark your Pull Request as a **`[draft]`** +- Pull Requests should be focused around a single exercise, issue, or change. - Pull Request titles and descriptions should make clear **what** has changed and **why**. - Please link  πŸ”—  to any related issues the PR addresses. - πŸ“› [ Open an issue ][open-an-issue]πŸ“›  and discuss it with  πŸ§°  maintainers _**before**_: @@ -78,8 +79,7 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil - Follow coding standards found in [PEP8][PEP8] (["For Humans" version here][pep8-for-humans]). - All files should have a proper [EOL][EOL]. This means one carriage return at the end of the final line of text files. - Otherwise, watch out  βš οΈ  for trailing spaces, extra blank lines, extra spaces, and spaces in blank lines. -- Continuous Integration is going to run **a lot** of checks. Pay attention to failures & try to understand and fix them. -- If you need help, comment in the PR or issue.  πŸ™‹πŸ½β€β™€οΈ   The maintainers are happy to help troubleshoot. +- Continuous Integration is going to run **a lot** of checks. Try to understand & fix any failures.
@@ -89,8 +89,8 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil 1.  Run [`configlet-lint`][configlet-lint] if the track [config.json](config-json) has been modified. 2.  Run [Prettier][prettier] on all markdown files. - - (_Optionally_) run [yapf][yapf] to help format your code, and give you a head start on making the linters happy. - 3.  Run [flake8][flake8] & [pylint][pylint] to ensure all Python code files conform to general code style standards. + - (_Optionally_) run [yapf][yapf] ([_config file_][.style.yapf]) to help format your code, and give you a head start on making the linters happy. + 3.  Run [flake8][flake8] ([_config file_][.flake8]) & [pylint][pylint] ([_config file_][pylintrc]) to ensure all Python code files conform to general code style standards. 4.  Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly. 5.  Run the `example.py` or `exemplar.py` file against the exercise test file to ensure that it passes without error. 6.  If you modified or created a `hints.md` file for a practice exercise, [regenerate](#generating-practice-exercise-documents) it. @@ -112,7 +112,9 @@ Our documents use [Markdown][markdown-language], with certain [alterations][exer
-## A Little More on Coding Standards +
+ +

A Little More on Coding Standards


1. We follow [PEP8][PEP8] (["For Humans" version here][pep8-for-humans]). @@ -124,16 +126,15 @@ Our documents use [Markdown][markdown-language], with certain [alterations][exer 4. We use [yapf][yapf] to auto-format our python files. Our `.style.yapf` config file is [.style.yapf][.style.yapf] in the top level of this repo. -If you have any questions or issues, don't hesitate to ask the maintainers -- they're always happy to help πŸ’› πŸ’™  - -Some of our code is old and does not (yet) conform to all these standards. We know it, and trust us, we're fixing it. But if you see  πŸ‘€  something,  πŸ‘„  say something. It'll motivate us to fix it! 🌈 - +
-### General Code Style TL;DR: +
+ General Code Style Summary +
- _**spaces**_, never `Tabs` - **4 space** indentation -- **120 character per line limit** (_as opposed to the Google limit of 79_) +- **120 character per line limit** (_as opposed to the default limit of 79_) - Variable, function, and method names should be `lower_case_with_underscores` (_aka "snake case"_) - Classes should be named in `TitleCase` (_aka "camel case"_) - **No single letter variable names** outside of a `lambda`. This includes loop variables and comprehensions. @@ -148,30 +149,49 @@ Some of our code is old and does not (yet) conform to all these standards. We k - Two lines between `Classes`, one line between `functions`. Other vertical whitespace as needed to help readability. - Always use an **`EOL`** to end a file. +
+ +
+ Test File Style (concept exercises) +
-### Concept Exercise Test Files - -- We have historically used [Unittest.TestCase][unittest] syntax, with [PyTest][pytest] as a test runner. -- We are transitioning to using (many) more PyTest features and syntax, but are leaving `Unittest` syntax in place where possible. -- Always check with a maintainer before introducing a PyTest feature in your tests. Not all PyTest features may be supported. -- Test **Classes** should be titled `Test`. e.g. `class CardGamesTest(unittest.TestCase):` - This is to help our test runner re-write them for display on the website. -- Test _methods_ or functions should begin with `test_`, and follow PEP8 naming. Try to make test case names descriptive but not too long. -- Favor [_parameterizing_][distinguishing-test-iterations] tests that vary only by input data. We use [unittest.TestCase.subTest][subtest] for this. An [example from Guido's Gorgeous Lasagna][guidos-gorgeous-lasagna-testfile]. A second [example from Card Games][card-games-testfile]. -- Avoid excessive line breaks or indentation - especially in parameterized tests. Excessive breaks & indentation within the `for` loops cause issues when formatting the test code for display on the website. -- Use [`enumerate()`][enumerate] where possible when looping in test cases. See [Card Games][card-games-testfile] for example usage. -- Favor using variable names like `inputs`, `data`, `input_data`, `test_data`, or `test_case_data` for test inputs. -- Favor using variable names like `results`, `expected`, `result_data`, `expected_data`, `expected_results` or `expected_outputs` for expected test outcomes. -- Favor putting the (not optional) assert failure message on it's own line outside of the `self.assert` method, and naming it `failure_msg`. See [Card Games][card-games-testfile] for example usage. -- Use `f-strings` over other methods for test failure messages. Make your messages as relevant and human-readable as possible. -- We relate the test cases for a particular task in an exercise to the **task number** via a custom [PyTest Marker][pytestmark]. These are decorators that take the form of ``@pytest.mark.task(taskno=)`. See [Guido's Gorgeous Lasagna][guidos-gorgeous-lasagna-testfile] for an example usage. -- For exercises that have large sets of data for inputs/outputs, we prefer to have **test data files**. These should be named with `_data` or `_test_data` at the end of the filename, and saved alongside the test case file. See the [Cater-Waiter][cater-waiter] exercise directory for an example of how we set this up. -- Test data files need to be added to the `editor` key within an exercises [`config.json` `files` key][exercise-config-json]. Check with a maintainer if you have questions or issues. +- [Unittest.TestCase][unittest] syntax, with [PyTest][pytest] as a test runner. + - We are transitioning to using more PyTest features/syntax, but are leaving `Unittest` syntax in place where possible. + - Always check with a maintainer before introducing a PyTest feature into your tests. +- Test **Classes** should be titled `Test`. **e.g.** `class CardGamesTest(unittest.TestCase):` +- Test method names should begin with `test_`. Try to make test case names descriptive but not too long. +- Favor [_parameterizing_][distinguishing-test-iterations] tests that only vary input data. Use [unittest.TestCase.subTest][subtest] for parameterization. + - An [example from Guido's Gorgeous Lasagna][guidos-gorgeous-lasagna-testfile]. + - A second [example from Card Games][card-games-testfile]. +- Avoid excessive line breaks or indentation - particularly in parameterized tests. + - Excessive breaks & indentation within the `for` loops cause issues when formatting the test code for display on the website. +- Use [`enumerate()`][enumerate] where possible when indexes are needed. See [Card Games][card-games-testfile] for example usage. +- Favor using names like `inputs`, `data`, `input_data`, `test_data`, or `test_case_data` for test inputs. +- Favor using names like `results`, `expected`, `result_data`, `expected_data`, or `expected_results` for test outcomes. +- Favor putting the assert failure message outside of `self.assert()`. Name it `failure_msg`. See [Card Games][card-games-testfile] for example usage. +- Favor `f-strings` for dynamic failure messages. Please make your error messages as relevant and human-readable as possible. +- We relate test cases to **task number** via a custom [PyTest Marker][pytestmark]. + - These take the form of `@pytest.mark.task(taskno=)`. See [Guido's Gorgeous Lasagna][guidos-gorgeous-lasagna-testfile] for an example. +- We prefer **test data files** when test inputs/ouputs are verbose. + - These should be named with `_data` or `_test_data` at the end of the filename, and saved alongside the test case file. + - See the [Cater-Waiter][cater-waiter] exercise directory for an example of this setup. + - **Test data files** need to be added under an `editor` key within [`config.json "files"`][exercise-config-json]. + - Check with a maintainer if you have questions or issues, or need help with an exercise `config.json`. - For new test files going forward, omit `if __name__ == "__main__": - unittest.main()`. `Unittest` will not be able to run these files stand-alone. -- Test files should be linted with both `flake8` and `pylint`. Both are known to toss false positives for imports and unused variables in test code. Where necessary, deploy the [`#noqa`][flake8-noqa] or [`#pylint disable=`][pylint-disable-check] comments to suppress false-positive warnings. See **line 16** of [Guido's Gorgeous Lasagna][guidos-gorgeous-lasagna-testfile] test file for an example of a pylint "skip". + unittest.main()`. +- Lint with both `flake8` and `pylint`. + - Both linters are known to toss false-positives for some testing patterns. + - Where necessary, deploy the [`#noqa`][flake8-noqa] or [`#pylint disable=`][pylint-disable-check] comments to suppress false-positive warnings. - See **line 16** of [Guido's Gorgeous Lasagna][guidos-gorgeous-lasagna-testfile] test file for an example of an override. -
+
+
+ +If you have any questions or issues, don't hesitate to ask the maintainers -- they're always happy to help πŸ’› πŸ’™  + +Some of our code is old and does not (yet) conform to all these standards. +_We know it, and trust us, we are working on fixing it._ But if you see  πŸ‘€  something,  πŸ‘„  say something. It'll motivate us to fix it! 🌈 + +
## πŸ‹οΈ A Little More on Exercises πŸ‹πŸ½β€β™€οΈ From 3d94dcc383d9135a6d6113f4ae4bd8f116618128 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Fri, 15 Oct 2021 03:02:24 -0700 Subject: [PATCH 20/31] More formatting and spelling and images. --- CONTRIBUTING.md | 165 ++++++++++++++++++++++++++++-------------------- 1 file changed, 97 insertions(+), 68 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9f7061e144..3c4fe2b978 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,6 +81,7 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil - Otherwise, watch out  βš οΈ  for trailing spaces, extra blank lines, extra spaces, and spaces in blank lines. - Continuous Integration is going to run **a lot** of checks. Try to understand & fix any failures. +

@@ -98,23 +99,23 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil

- -## πŸ“„ A Little More on Prose Writing Style and Standards + +

A Little More on Prose Writing Style and Standards


-Non-code content (_exercise introductions & instructions, hints, concept write-ups, documentation etc._) should be written in [American English][american-english]. We strive to watch [the words we use][the-words-that-we-use]. +Non-code content (_exercise introductions & instructions, hints, concept write-ups, documentation etc._) should be written in [American English][american-english]. +We strive to watch [the words we use][the-words-that-we-use]. -When a word or phrase usage is contested/ambiguous, we default to what is best understood by our international community of learners, even if it "sounds a little weird" to a "native" American English speaker. +When a word or phrase usage is contested/ambiguous, we default to what is best understood by our international community of learners, even if it "sounds a little weird" to a "native" American English speaker. Our documents use [Markdown][markdown-language], with certain [alterations][exercism-markdown-widgets] & [additions][exercism-internal-linking]. Here is our full [Markdown Specification][exercism-markdown-specification].  πŸ“ We format/lint our Markdown with [Prettier][prettier]. βœ¨
- -
- +

A Little More on Coding Standards

+
1. We follow [PEP8][PEP8] (["For Humans" version here][pep8-for-humans]). @@ -150,7 +151,7 @@ Our documents use [Markdown][markdown-language], with certain [alterations][exer - Always use an **`EOL`** to end a file.
- +
Test File Style (concept exercises)
@@ -172,7 +173,7 @@ Our documents use [Markdown][markdown-language], with certain [alterations][exer - Favor `f-strings` for dynamic failure messages. Please make your error messages as relevant and human-readable as possible. - We relate test cases to **task number** via a custom [PyTest Marker][pytestmark]. - These take the form of `@pytest.mark.task(taskno=)`. See [Guido's Gorgeous Lasagna][guidos-gorgeous-lasagna-testfile] for an example. -- We prefer **test data files** when test inputs/ouputs are verbose. +- We prefer **test data files** when test inputs/outputs are verbose. - These should be named with `_data` or `_test_data` at the end of the filename, and saved alongside the test case file. - See the [Cater-Waiter][cater-waiter] exercise directory for an example of this setup. - **Test data files** need to be added under an `editor` key within [`config.json "files"`][exercise-config-json]. @@ -189,68 +190,85 @@ Our documents use [Markdown][markdown-language], with certain [alterations][exer If you have any questions or issues, don't hesitate to ask the maintainers -- they're always happy to help πŸ’› πŸ’™  Some of our code is old and does not (yet) conform to all these standards. -_We know it, and trust us, we are working on fixing it._ But if you see  πŸ‘€  something,  πŸ‘„  say something. It'll motivate us to fix it! 🌈 +_**We know it, and trust us, we are working on fixing it.**_ But if you see  πŸ‘€  something,  πŸ‘„  say something. It will motivate us to fix it! 🌈
-## πŸ‹οΈ A Little More on Exercises πŸ‹πŸ½β€β™€οΈ + +

Python Versions

-- Each exercise must be self-contained. Please do not use or reference files that reside outside the given exercise directory. "Outside" files will not be included if a student fetches the exercise via the CLI. +
-- Each exercise/problem should include a complete test suite, an example/exemplar solution, and a stub file ready for student implementation. +This track officially supports Python = `3.8` +The track `test runner`, `analyzer`, and `representer` run in docker on `python:3.9-slim`. - - See [Concept Exercise Anatomy][concept-exercise-anatomy], or [Practice Exercise Anatomy][practice-exercise-anatomy] depending on which type of exercise you are contributing to. +- All exercises should be written for compatibility with Python = `3.8` or `3.9`. +- Version backward _incompatibility_ (*e.g* an exercise using a `3.8` or `3.9` **only** feature) should be clearly noted in any exercise hits, links, introductions or other notes. -
- Concept Exercise Checklist> -
+- Here is an example of how the Python documentation handles [version-tagged  πŸ· ][version-tagged-language-features] feature introduction. -
+- _Most_ exercises will work with Python `3.6+`, and _many_ are compatible with Python `2.7+`. + - Please do not change existing exercises to add new language features without consulting with a maintainer first. + - We  πŸ’› πŸ’™  modern Python, but we _also_ want to avoid student confusion when it comes to which Python versions support brand-new features. -
- Practice Exercise Checklist> -
+- All test suites and example solutions must work in all Python versions that we currently support. When in doubt about a feature, please check with maintainers. -- **Practice exercise**, descriptions and instructions come from a centralized, cross-track [problem specifications][problem-specifications] repository. +
+ +
+ + +

A Little More on Exercises

+ +
+ +- Each exercise must be self-contained. Please do not use or reference files that reside outside the given exercise directory. "Outside" files will not be included if a student fetches the exercise via the Command line Interface. + +- Each exercise/problem should include + - a complete test suite, + - an example/exemplar solution, + - a stub file ready for student implementation. +- For specifications, refer to the links below, depending on which type of exercise you are contributing to. + - [Concept Exercise Anatomy][concept-exercise-anatomy] + - [Practice Exercise Anatomy][practice-exercise-anatomy] + +- **Practice exercise**, descriptions and instructions come from a centralized, cross-track [problem specifications][problem-specifications] repository. - Any updates or changes need to be proposed/approved in `problem-specifications` first. - If Python-specific changes become necessary, they need to be appended to the canonical instructions by creating a `instructions.append.md` file in this (`exercism/Python`) repository. -- Practice Exercise **Test Suits** for many practice exercises are similarly [auto-generated][##Auto-Generated Test Files and Test Templates] from data in [problem specifications][problem-specifications]. +- Practice Exercise **Test Suits** for many practice exercises are similarly [auto-generated](#auto-generated-files) from data in [problem specifications][problem-specifications]. - Any changes to them need to be proposed/discussed in the `problem-specifications` repository and approved by **3 track maintainers**, since changes could potentially affect many (_or all_) exercism language tracks. - If Python-specific test changes become necessary, they can be appended to the exercise `tests.toml` file. - πŸ“› [ **Please file an issue**][open-an-issue] πŸ“›  and check with maintainers before adding any Python-specific tests. +
+
+
+ βœ…   Concept Exercise Checklist +
-
- +
+ βœ…   Practice Exercise Checklist +
-## Python Versions
-This track officially supports Python = `3.8` The track `test runner`, `analyzer`, and `representer` run in docker on `python:3.9-slim`. - -* All exercises should be written for compatibility with Python = `3.8` or `3.9`. -* Version backward _incompatibility_ (*e.g* an exercise using a `3.8` or `3.9` **only** feature) should be clearly noted in any exercise hits, links, introductions or other notes. - -* Here is an example of how the Python documentation handles [version-tagged  πŸ· ][version-tagged-language-features] feature introduction. - -* _Most_ exercises will work with Python `3.6+`, and _many_ are compatible with Python `2.7+`. Please do not change existing exercises to add new language features without consulting with a maintainer first. We  πŸ’› πŸ’™  modern Python, but we _also_ want to avoid student confusion when it comes to which Python versions support brand-new features. - -- All test suites and example solutions must work in all Python versions that we currently support. When in doubt about a feature, please check with maintainers.
+ +

External Libraries and Dependencies

-## External Libraries and Dependencies +
-Our tooling (_runners, analyzers and representers_) runs in isolated containers within the exercism website. Because of this, exercises cannot rely on third-party or external libraries. Any library needed for an exercise or exercise tests must be incorporated as part of the tooling build, and noted for students who are using the CLI to solve problems locally. +Our tooling (_runners, representers, and analyzers_) runs in isolated containers within the exercism website. Because of this isolation, exercises cannot rely on third-party or external libraries. Any library needed for an exercise or exercise tests must be incorporated as part of a tooling build, and noted for students who are using the CLI to solve problems locally. If your exercise depends on a third-party library (_aka not part of standard Python_), please consult with maintainers about it. We may or may not be able to accommodate the package.
- -## Auto-Generated Test Files and Test Templates + +

Auto-Generated Test Files and Test Templates


@@ -260,11 +278,7 @@ Changes to practice exercise _specifications_ should be raised/PR'd in [problem If a practice exercise has an auto-generated `_test.py` file, there will be a `.meta/template.j2` and a `.meta/tests.toml` file in the exercise directory. If an exercise implements Python track-specific tests, there may be a `.meta/additional_tests.json` to define them. These `additional_tests.json` files will automatically be included in test generation. -Practice exercise `_test.py` files are generated/regenerated via the [Python Track Test Generator][python-track-test-generator]. Please reach out to a maintainer if you need any help with the process. - -
- -### Python Practice Exercise structure for auto-generated tests +_Exercise Structure with Auto-Generated Test Files_ ```Bash [/ @@ -278,44 +292,59 @@ Practice exercise `_test.py` files are generated/regenerated via β”œβ”€β”€ .py #stub file └── -## Generating Practice Exercise Documents - -**You will need:** -- A local clone of the [problem-specifications] repository. -- [configlet] +Practice exercise `_test.py` files are generated/regenerated via the [Python Track Test Generator][python-track-test-generator]. +Please reach out to a maintainer if you need any help with the process. -**Regenerating all Practice Exercise Documents:** +
+ +

Implementing Practice Exercise Tests

+
-``` -configlet generate --spec-path path/to/problem/specifications -``` +If an unimplemented exercise has a `canonical-data.json` file in the [problem-specifications] repository, a generation template must be created. See the Python track [test generator documentation][python-track-test-generator] for more information. -**Regenerating an Individual Exercises Documents:** +If an unimplemented exercise does not have a `canonical-data.json` file, the test file must be written manually. -``` -configlet generate --spec-path path/to/problem/specifications --only example-exercise -``` +
+ +

Implementing Practice Exercise Example Solutions

+
-### Implementing Practice Exercise Tests +**Example solution files serve two purposes only:** +1. Verification of the tests +2. Example implementation for mentor/student reference -If an unimplemented exercise has a `canonical-data.json` file in the [problem-specifications] repository, a generation template must be created. See the Python track [test generator documentation][python-track-test-generator] for more information. +Unlike `concept` exercise, practice exercise `example.py` files are **NOT** intended as as a "best practice" or "standard". +They are provided as proof that there is an acceptable and testable answer to the practice exercise. -If an unimplemented exercise does not have a `canonical-data.json` file, the test file must be written manually. +
+ +

Implementing Track-specific Practice Exercises

+
-### Practice Exercise Example solutions +Implementing Track-specific Practice Exercises is similar to implementing a `canonical` exercise that has no `canonical-data.json`. But in addition to the tests, the exercise documents (_instructions, etc._) will also need to be written manually. Carefully follow the structure of generated exercise documents and the [exercism practice exercise specification][practice-exercises]. +
-Example solution files serve two purposes: +

Generating Practice Exercise Documents

+
+You will need -1. Verification of the tests -2. Example implementation for mentor/student reference +1.  A local clone of the [problem-specifications] repository. +2.  [configlet] -Unlike concept exercise, practice exercise `example.py` files are NOT intended as as a "best practice" or "standard". They are provided as proof that there is an acceptable and testable answer to the practice exercise. +

For Individual Exercises

+```bash +configlet generate --spec-path path/to/problem/specifications --only example-exercise +``` +

For all Practice Exercises

-## Implementing Track-specific Practice Exercises +```bash +configlet generate --spec-path path/to/problem/specifications +``` -Similar to implementing a canonical exercise that has no `canonical-data.json`, but the exercise documents will also need to be written manually. Carefully follow the structure of generated exercise documents and the [exercism practice exercise specification][practice-exercises]. +
[.flake8]: https://github.com/exercism/python/blob/main/.flake8 From 0a9240783235772c24c420dd308f8b45050eaee9 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Fri, 15 Oct 2021 03:09:52 -0700 Subject: [PATCH 21/31] More formatting and spelling and images. --- CONTRIBUTING.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3c4fe2b978..73cbc3e948 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,9 +58,8 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil 🐍  _But we should talk before you take a whole lot of time or energy implementing anything._
- -## In General - + +

In General


- Maintainers are happy to review your work and help troubleshoot with you. πŸ’› πŸ’™  From f36511c656d37f60539ca2d27e04caee173e5248 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Fri, 15 Oct 2021 03:39:42 -0700 Subject: [PATCH 22/31] More formatting and spelling and images. --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 73cbc3e948..6d83904b0a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,7 @@ Exercises are grouped into **concept** exercises which teach the [Python syllabu
- + 🌟🌟  If you have not already done so, please take a moment to read our [Code of Conduct][exercism-code-of-conduct]. πŸŒŸπŸŒŸ  It might also be helpful to look at [Being a Good Community Member][being-a-good-community-member] & [The words that we use][the-words-that-we-use]. @@ -28,7 +28,7 @@ It might also be helpful to look at [Being a Good Community Member][being-a-good Some defined roles in our community: [Contributors][exercism-contributors] **|** [Mentors][exercism-mentors] **|** [Maintainers][exercism-track-maintainers] **|** [Admins][exercism-admins]
- + ✨ πŸ¦„  _**Want to jump directly into Exercism specifications & detail?**_      [Structure][exercism-track-structure] **|** [Tasks][exercism-tasks] **|** [Concepts][exercism-concepts] **|** [Concept Exercises][concept-exercises] **|** [Practice Exercises][practice-exercises] **|** [Presentation][exercise-presentation] From c108783e90a37ffab01d14db418182414e82927a Mon Sep 17 00:00:00 2001 From: BethanyG Date: Fri, 15 Oct 2021 03:56:47 -0700 Subject: [PATCH 23/31] More formatting and spelling and images. --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6d83904b0a..e99acfc05b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -99,7 +99,7 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil
-

A Little More on Prose Writing Style and Standards

+

Prose Writing Style and Standards


@@ -113,7 +113,7 @@ Our documents use [Markdown][markdown-language], with certain [alterations][exer
-

A Little More on Coding Standards

+

Coding Standards


@@ -266,7 +266,7 @@ Our tooling (_runners, representers, and analyzers_) runs in isolated containers If your exercise depends on a third-party library (_aka not part of standard Python_), please consult with maintainers about it. We may or may not be able to accommodate the package.
- +

Auto-Generated Test Files and Test Templates


From 67d147db5727f1da446c58e4b06721be1196d0e5 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Fri, 15 Oct 2021 03:59:30 -0700 Subject: [PATCH 24/31] More formatting and spelling and images. --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e99acfc05b..9a70b7a1d6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,8 +81,6 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil - Continuous Integration is going to run **a lot** of checks. Try to understand & fix any failures.
-
-
⚠️  Pre-Commit Checklist βš οΈ
@@ -97,6 +95,7 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil

+

Prose Writing Style and Standards

@@ -323,9 +322,10 @@ They are provided as proof that there is an acceptable and testable answer to th
Implementing Track-specific Practice Exercises is similar to implementing a `canonical` exercise that has no `canonical-data.json`. But in addition to the tests, the exercise documents (_instructions, etc._) will also need to be written manually. Carefully follow the structure of generated exercise documents and the [exercism practice exercise specification][practice-exercises]. +
-

Generating Practice Exercise Documents

+

Generating Practice Exercise Documents


You will need From 5b69b1e37f495ee78590f7bf0ab7173362e8f2fc Mon Sep 17 00:00:00 2001 From: BethanyG Date: Fri, 15 Oct 2021 04:51:35 -0700 Subject: [PATCH 25/31] Added checklists and more typo correction.. --- CONTRIBUTING.md | 40 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a70b7a1d6..2ab4a2b882 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -95,7 +95,6 @@ When in doubt, πŸ“› [ Open an issue ][open-an-issue]πŸ“› . We wil

-

Prose Writing Style and Standards

@@ -243,11 +242,45 @@ The track `test runner`, `analyzer`, and `representer` run in docker on `python:

- βœ…   Concept Exercise Checklist + + βœ…   Concept Exercise Checklist + +
+ + - [ ] `.docs/hints.md` + - [ ] `.docs/instructions.md` + - [ ] `.docs/introduction.md` + - [ ] `.meta/config.json` + - [ ] `.meta/design.md` + - [ ] `.meta/exemplar.py` (_exemplar solution_) + - [ ] `_test.py` (_test file_) + - [ ] `.py` (_stub file_) + - [ ] `concepts/../introduction.md` + - [ ] `concepts/../about.md` + - [ ] `concepts/../links.json` + - [ ] `concepts/../.meta/config.json` +
- βœ…   Practice Exercise Checklist + + βœ…   Practice Exercise Checklist + +
+ + - [ ] `.docs/instructions.md`(**required**) + - [ ] `.docs/introduction.md`(_optional_) + - [ ] `.docs/introduction.append.md`(_optional_) + - [ ] `.docs/instructions.append.md` (_optional_) + - [ ] `.docs/hints.md`(_optional_) + - [ ] `.meta/config.json` (**required**) + - [ ] `.meta/example.py` (**required**) + - [ ] `.meta/design.md` (_optional_) + - [ ] `.meta/template.j2` (_template for generating tests from canonical data_) + - [ ] `.meta/tests.toml` (_tests configuration from canonical data_) + - [ ] `_test.py` (_**auto-generated from canonical data**_) + - [ ] `.py` (**required**) +
@@ -356,7 +389,6 @@ configlet generate --spec-path path/to/problem/specifications [concept-exercise-anatomy]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md [concept-exercises]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md [config-json]: https://github.com/exercism/javascript/blob/main/config.json -[configlet-general]: https://github.com/exercism/configlet [configlet]: https://github.com/exercism/docs/blob/main/building/configlet/generating-documents.md [configlet-lint]: https://github.com/exercism/configlet#configlet-lint [distinguishing-test-iterations]: https://docs.python.org/3/library/unittest.html#distinguishing-test-iterations-using-subtests From 881c9af73a5855b5745eb25ddfc881ea621773b4 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Fri, 15 Oct 2021 06:00:42 -0700 Subject: [PATCH 26/31] Some finalish touch-up. --- CONTRIBUTING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2ab4a2b882..9c266a26d3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -380,17 +380,18 @@ configlet generate --spec-path path/to/problem/specifications [.flake8]: https://github.com/exercism/python/blob/main/.flake8 +[.style.yapf]: https://github.com/exercism/python/blob/main/.style.yapf [EOL]: https://en.wikipedia.org/wiki/Newline [PEP8]: https://www.python.org/dev/peps/pep-0008/ [american-english]: https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md [being-a-good-community-member]: https://github.com/exercism/docs/tree/main/community/good-member -[cater-waiter]: https://github.com/exercism/python/tree/main/exercises/concept/cater-waiter [card-games-testfile]: https://github.com/exercism/python/blob/main/exercises/concept/card-games/lists_test.py +[cater-waiter]: https://github.com/exercism/python/tree/main/exercises/concept/cater-waiter [concept-exercise-anatomy]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md [concept-exercises]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md [config-json]: https://github.com/exercism/javascript/blob/main/config.json -[configlet]: https://github.com/exercism/docs/blob/main/building/configlet/generating-documents.md [configlet-lint]: https://github.com/exercism/configlet#configlet-lint +[configlet]: https://github.com/exercism/docs/blob/main/building/configlet/generating-documents.md [distinguishing-test-iterations]: https://docs.python.org/3/library/unittest.html#distinguishing-test-iterations-using-subtests [enumerate]: https://docs.python.org/3/library/functions.html#enumerate [exercise-config-json]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md#full-example @@ -408,8 +409,8 @@ configlet generate --spec-path path/to/problem/specifications [exercism-track-structure]: https://github.com/exercism/docs/tree/main/building/tracks [exercism-website]: https://exercism.org/ [exercism-writing-style]: https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md -[flake8]: http://flake8.pycqa.org/ [flake8-noqa]: https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html#in-line-ignoring-errors +[flake8]: http://flake8.pycqa.org/ [google-coding-style]: https://google.github.io/styleguide/pyguide.html [guidos-gorgeous-lasagna-testfile]: https://github.com/exercism/python/blob/main/exercises/concept/guidos-gorgeous-lasagna/lasagna_test.py [help-wanted]: https://github.com/exercism/python/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22 @@ -422,14 +423,13 @@ configlet generate --spec-path path/to/problem/specifications [practice-exercises]: https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md [prettier]: https://prettier.io/ [problem-specifications]: https://github.com/exercism/problem-specifications +[pylint-disable-check]: https://pylint.pycqa.org/en/latest/user_guide/message-control.html#block-disables [pylint]: https://pylint.pycqa.org/en/v2.11.1/user_guide/index.html [pylintrc]: https://github.com/exercism/python/blob/main/pylintrc -[pylint-disable-check]: https://pylint.pycqa.org/en/latest/user_guide/message-control.html#block-disables [pytest]: https://docs.pytest.org/en/6.2.x/contents.html [pytestmark]: https://docs.pytest.org/en/6.2.x/example/markers.html [python-syllabus]: https://exercism.org/tracks/python/concepts [python-track-test-generator]: https://github.com/exercism/python/blob/main/docs/GENERATOR.md -[.style.yapf]: https://github.com/exercism/python/blob/main/.style.yapf [subtest]: https://docs.python.org/3/library/unittest.html#unittest.TestCase.subTest [the-words-that-we-use]: https://github.com/exercism/docs/blob/main/community/good-member/words.md [unittest]: https://docs.python.org/3/library/unittest.html#unittest.TestCase From 3e3a7a897ac3f60aa6102d56eea32f4eb3054f8b Mon Sep 17 00:00:00 2001 From: BethanyG Date: Fri, 15 Oct 2021 06:00:57 -0700 Subject: [PATCH 27/31] Revamped README. --- README.md | 86 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 59 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 9dfd383f98..6064675988 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,84 @@ -:wave: Thank you for your interest in contributing to the exercism Python track! +
-:warning: **Please Note** :warning: + +

Exercism Python Track

-We are currently in the middle of re-arranging and re-configuring our track for exercism V3. +
-We're **super-excited** :tada: :rocket: -- _and we really want you to be involved!_ -- but all that inital configuration work means **our maintainers can't accept unsolicited contributions at this time.** - -Please check our [issue list](https://github.com/exercism/python/labels/help%20wanted) for tasks we've flagged as `[help wanted]` -- _and check back_ -- we'll be adding (_many more!_) tasks with that flag in the coming weeks as we update our documentation and identify exercises, documents, and bugs that need to be worked on before our V3 launch. +![Exercism_II](https://img.shields.io/badge/Exercism--Built-9101FF?logo=python&logoColor=FFDF58&labelColor=3D7AAB&label=Python-Powered) +[![Build Status](https://github.com/exercism/python/workflows/Exercises%20check/badge.svg)](https://github.com/exercism/python/actions?query=workflow%3A%22Exercises+check%22) +[![Join the chat at https://gitter.im/exercism/python](https://badges.gitter.im/exercism/python.svg)](https://gitter.im/exercism/python?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) ---- +
-# Exercism Python Track +Hi.  πŸ‘‹πŸ½  πŸ‘‹  **We are happy you are here.**  πŸŽ‰ πŸŒŸ -[![Build Status](https://github.com/exercism/python/workflows/Exercises%20check/badge.svg)](https://github.com/exercism/python/actions?query=workflow%3A%22Exercises+check%22) -[![Join the chat at https://gitter.im/exercism/python](https://badges.gitter.im/exercism/python.svg)](https://gitter.im/exercism/python?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) +**`exercsim/Python`** is one of many programming language tracks on [exercism(dot)org][exercism-website]. +This repo holds all the instructions, tests, code, & support files for Python *exercises* currently under development or implemented & available for students. -Exercism exercises in Python + 🌟   Track exercises support Python `3.8`. + 🌟   Track tooling (_test-runner, representer, analyzer, and Continuous Integration_) runs on Python `3.9`. +Exercises are grouped into **concept** exercises which teach the [Python syllabus][python-syllabus], and **practice** exercises, which are unlocked by progressing in the syllabus tree  πŸŒ΄  . Concept exercises are constrained to a small set of language or syntax features. Practice exercises are open-ended, and can be used to practice concepts learned, try out new techniques, and _play_. These two exercise groupings can be found in the track [config.json][config-json], and under the `python/exercises` directory. -## Contributing Guide +
-Our WIP V3 documentation can be found here: [exercism V3](https://github.com/exercism/docs). + +🌟🌟  Please take a moment to read our [Code of Conduct][exercism-code-of-conduct]. πŸŒŸπŸŒŸ  +It might also be helpful to look at [Being a Good Community Member][being-a-good-community-member] & [The words that we use][the-words-that-we-use]. -### Testing +Some defined roles in our community: [Contributors][exercism-contributors] **|** [Mentors][exercism-mentors] **|** [Maintainers][exercism-track-maintainers] **|** [Admins][exercism-admins] -All exercises must be compatible with Python version 3.8 upwards. We no longer support Python 2.x. +
+ -To test a single exercise: -``` -python3 test/check-exercises.py [exercise-name] -``` +We πŸ’› πŸ’™   Pull Requests. **But our maintainers generally can't accept _unsolicited_ PRs.** +Check our [help wanted][open-issues] list or [open an issue ][open-an-issue] for discussion first. +We  βœ¨πŸ’™  πŸ’›  πŸ’™ ✨  PRs that follow our **[Contributing Guidelines][contributing-guidelines]**. -To test all exercises: -``` -python3 test/check-exercises.py -``` +
+ -### Code Style +✨ πŸ¦„  _**Want to jump directly into Exercism specifications & detail?**_ +     [Structure][exercism-track-structure] **|** [Tasks][exercism-tasks] **|** [Concepts][exercism-concepts] **|** [Concept Exercises][concept-exercises] **|** [Practice Exercises][practice-exercises] **|** [Presentation][exercise-presentation] +     [Writing Style Guide][exercism-writing-style] **|** [Markdown Specification][exercism-markdown-specification] (_ βœ¨   versions available in [contributing][website-contributing-section] on [exercism(dot)org][exercism-website]._) -The Python code in this repo is meant to follow the [PEP8 style guide](https://www.python.org/dev/peps/pep-0008/) (a stylized version http://pep8.org). +
-This repo uses [flake8](http://flake8.readthedocs.org/en/latest/) with default settings to enforce the coding standard. +If you are here to help out with [open issues][open-issues], you have our gratitude  πŸ™Œ  πŸ™ŒπŸ½. +Anything with [`help wanted`] and without a [`Claimed`] tag is up for grabs - just comment, and we will reserve it for you.  πŸŒˆ   ✨ -### CI build +Here to suggest a new feature or new exercise?? **Hooray!**  πŸŽ‰   +_Please keep in mind [Chesterton's Fence][chestertons-fence]._ +_Following the principals there when making your suggestions will likely result in a faster and more enthusiastic response from maintainers._ ## License This repository uses the [MIT License](/LICENSE). + +[exercism-website]: https://exercism.org/ +[exercise-presentation]: https://github.com/exercism/docs/blob/main/building/tracks/presentation.md +[exercism-admins]: https://github.com/exercism/docs/blob/main/community/administrators.md +[the-words-that-we-use]: https://github.com/exercism/docs/blob/main/community/good-member/words.md +[exercism-writing-style]: https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md +[concept-exercises]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md +[practice-exercises]: https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md +[exercism-contributors]: https://github.com/exercism/docs/blob/main/community/contributors.md +[being-a-good-community-member]: https://github.com/exercism/docs/tree/main/community/good-member +[exercism-markdown-specification]: https://github.com/exercism/docs/blob/main/building/markdown/markdown.md +[exercism-concepts]: https://github.com/exercism/docs/blob/main/building/tracks/concepts.md +[exercism-code-of-conduct]: https://exercism.org/docs/using/legal/code-of-conduct +[config-json]: https://github.com/exercism/javascript/blob/main/config.json +[python-syllabus]: https://exercism.org/tracks/python/concepts +[exercism-track-maintainers]: https://github.com/exercism/docs/blob/main/community/maintainers.md +[exercism-tasks]: https://exercism.org/docs/building/product/tasks +[website-contributing-section]: https://exercism.org/docs/building +[exercism-track-structure]: https://github.com/exercism/docs/tree/main/building/tracks +[exercism-mentors]: https://github.com/exercism/docs/tree/main/mentoring +[open-issues]: https://github.com/exercism/python/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22 +[chestertons-fence]: https://github.com/exercism/docs/blob/main/community/good-member/chestertons-fence.md +[contributing-guidelines]: https://github.com/exercism/python/blob/main/CONTRIBUTING.md +[open-an-issue]: https://github.com/exercism/python/issues/new/choose \ No newline at end of file From da1c5180dfd5cf32d13e7c9002f038c86e48bf4c Mon Sep 17 00:00:00 2001 From: BethanyG Date: Fri, 15 Oct 2021 06:05:31 -0700 Subject: [PATCH 28/31] Formatting. AGAIN. --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6064675988..82ec69d839 100644 --- a/README.md +++ b/README.md @@ -43,17 +43,18 @@ We  βœ¨πŸ’™  πŸ’›  πŸ’™ ✨  PRs that follow our **[Contribu ✨ πŸ¦„  _**Want to jump directly into Exercism specifications & detail?**_      [Structure][exercism-track-structure] **|** [Tasks][exercism-tasks] **|** [Concepts][exercism-concepts] **|** [Concept Exercises][concept-exercises] **|** [Practice Exercises][practice-exercises] **|** [Presentation][exercise-presentation] -     [Writing Style Guide][exercism-writing-style] **|** [Markdown Specification][exercism-markdown-specification] (_ βœ¨   versions available in [contributing][website-contributing-section] on [exercism(dot)org][exercism-website]._) +     [Writing Style Guide][exercism-writing-style] **|** [Markdown Specification][exercism-markdown-specification] (_ βœ¨   version in [contributing][website-contributing-section] on [exercism(dot)org][exercism-website]._)
If you are here to help out with [open issues][open-issues], you have our gratitude  πŸ™Œ  πŸ™ŒπŸ½. -Anything with [`help wanted`] and without a [`Claimed`] tag is up for grabs - just comment, and we will reserve it for you.  πŸŒˆ   ✨ +Anything with [`help wanted`] and without a [`Claimed`] tag is up for grabs +- - just comment, and we will reserve it for you.  πŸŒˆ   ✨ Here to suggest a new feature or new exercise?? **Hooray!**  πŸŽ‰   -_Please keep in mind [Chesterton's Fence][chestertons-fence]._ +Please keep in mind [Chesterton's Fence][chestertons-fence]. _Following the principals there when making your suggestions will likely result in a faster and more enthusiastic response from maintainers._ ## License From c473dfe3b37cf9ce6b0e52c6b3d303cc62185b6c Mon Sep 17 00:00:00 2001 From: BethanyG Date: Fri, 15 Oct 2021 06:07:36 -0700 Subject: [PATCH 29/31] And MOAR formatting. AGAIN. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 82ec69d839..d7767d3b94 100644 --- a/README.md +++ b/README.md @@ -50,11 +50,11 @@ We  βœ¨πŸ’™  πŸ’›  πŸ’™ ✨  PRs that follow our **[Contribu If you are here to help out with [open issues][open-issues], you have our gratitude  πŸ™Œ  πŸ™ŒπŸ½. Anything with [`help wanted`] and without a [`Claimed`] tag is up for grabs -- - just comment, and we will reserve it for you.  πŸŒˆ   ✨ +Comment on the issue and we will reserve it for you.  πŸŒˆ   ✨ Here to suggest a new feature or new exercise?? **Hooray!**  πŸŽ‰   -Please keep in mind [Chesterton's Fence][chestertons-fence]. +Please keep in mind [Chesterton's Fence][chestertons-fence]. _Following the principals there when making your suggestions will likely result in a faster and more enthusiastic response from maintainers._ ## License From 9b306579331152a1d4e09a9390c886762797d3a2 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Fri, 15 Oct 2021 06:08:39 -0700 Subject: [PATCH 30/31] And MOAR formatting. AGAIN. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d7767d3b94..cdb5498c95 100644 --- a/README.md +++ b/README.md @@ -49,13 +49,13 @@ We  βœ¨πŸ’™  πŸ’›  πŸ’™ ✨  PRs that follow our **[Contribu If you are here to help out with [open issues][open-issues], you have our gratitude  πŸ™Œ  πŸ™ŒπŸ½. -Anything with [`help wanted`] and without a [`Claimed`] tag is up for grabs +Anything with [`help wanted`] and without a [`Claimed`] tag is up for grabs. Comment on the issue and we will reserve it for you.  πŸŒˆ   ✨ Here to suggest a new feature or new exercise?? **Hooray!**  πŸŽ‰   Please keep in mind [Chesterton's Fence][chestertons-fence]. -_Following the principals there when making your suggestions will likely result in a faster and more enthusiastic response from maintainers._ +_Following the principals there when making your suggestions will likely result in a faster & more enthusiastic response from maintainers._ ## License This repository uses the [MIT License](/LICENSE). From c17f463affb2a41fa2348be629204e74c2850821 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Fri, 15 Oct 2021 06:19:03 -0700 Subject: [PATCH 31/31] A last time for formatting, maybe?. --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index cdb5498c95..257f5cdf2c 100644 --- a/README.md +++ b/README.md @@ -46,16 +46,18 @@ We  βœ¨πŸ’™  πŸ’›  πŸ’™ ✨  PRs that follow our **[Contribu      [Writing Style Guide][exercism-writing-style] **|** [Markdown Specification][exercism-markdown-specification] (_ βœ¨   version in [contributing][website-contributing-section] on [exercism(dot)org][exercism-website]._)
- + If you are here to help out with [open issues][open-issues], you have our gratitude  πŸ™Œ  πŸ™ŒπŸ½. Anything with [`help wanted`] and without a [`Claimed`] tag is up for grabs. Comment on the issue and we will reserve it for you.  πŸŒˆ   ✨ -Here to suggest a new feature or new exercise?? **Hooray!**  πŸŽ‰   +
+ +Here to suggest a new feature or new exercise?? **Hooray!**  πŸŽ‰   Please keep in mind [Chesterton's Fence][chestertons-fence]. -_Following the principals there when making your suggestions will likely result in a faster & more enthusiastic response from maintainers._ +_Thoughtful suggestions will likely result faster & more enthusiastic responses from maintainers._ ## License This repository uses the [MIT License](/LICENSE).