# Contributing 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?** 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
- 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 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. - 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 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 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/).
## 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. - 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. - For **practice exercise**, 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 `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.
## 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 ################################## >>>>>>> Formatting Update ## 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 ```Bash exercises/[EXERCISE]/ โ”œโ”€โ”€ [EXERCISE].py โ”œโ”€โ”€ [EXERCISE]_test.py โ”œโ”€โ”€ example.py โ”œโ”€โ”€ .meta โ”‚ โ”œโ”€โ”€ template.j2 โ”‚ โ”œโ”€โ”€ additional_tests.json โ”‚ โ””โ”€โ”€ hints.md โ””โ”€โ”€ README.md ``` Files: | File | Description | Source | |:--- |:--- |:--- | | [[EXERCISE].py](exercises/two-fer/two_fer.py) | Solution stub | Manually created by the implementer | | [[EXERCISE]_test.py](exercises/two-fer/two_fer_test.py) | Exercise test suite | Automatically generated if `.meta/template.j2` is present, otherwise manually created by the implementer | | [example.py](exercises/two-fer/example.py) | Example solution used to automatically verify the `[EXERCISE]_test.py` suite | Manually created by the implementer | | [.meta/template.j2](exercises/two-fer/.meta/template.j2) | Test generation template; if present used to automatically generate `[EXERCISE]_test.py` (See [generator documentation](docs/GENERATOR.md)) | Manually created by implementer | | [.meta/additional_tests.json](exercises/word-count/.meta/additional_tests.json) | Defines additional track-specific test cases; if `.meta/template.j2` is also present these test will be incorporated into the automatically generated `[EXERCISE]_test.py` | Manually created by the implementer | | [.meta/hints.md](exercises/high-scores/.meta/hints.md) | Contains track-specific hints that are automatically included in the generated `README.md` file | Manually created by the implementer | | [README.md](exercises/two-fer/README.md) | Exercise README | [Generated by `configlet` tool](#generating-exercise-readmes) | ### Generating Exercise READMEs #### Requirements - A local clone of the [problem-specifications] repository. - [configlet]: may be obtained either by - (**Recommended**) Following installation instructions at the above link - Running `bin/fetch-configlet` (`configlet` binary will be downloaded to the repository `bin/`) #### Generating all READMEs ``` configlet generate --spec-path path/to/problem/specifications ``` #### Generating a single README ``` configlet generate --spec-path path/to/problem/specifications --only example-exercise ``` ### Implementing 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 does not have a `canonical-data.json` file, the test file must be written manually (use existing test files for examples). ### 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" }, ``` Fields
slug Hyphenated lowercase exercise name
uuid Generate using configlet uuid
core Set to false; core exercises are decided by track maintainers
unlocked_by Slug for the core exercise that unlocks the new one
difficulty 1 through 10. Discuss with reviewer if uncertain.
topics Array 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. ## 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 [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/