|
1 | | -# Contributing |
| 1 | +# Contributing Guide |
2 | 2 |
|
3 | | -Hi. 👋🏽 👋 |
| 3 | +This document supplements the [Exercism contributing guide]; all contributors should read that document before proceeding. |
4 | 4 |
|
5 | | -Thank you so much for your interest in contributing to the Python track! **We are happy you are here.** 🌟 🎉 |
| 5 | +## Table of Contents |
6 | 6 |
|
7 | | - |
8 | | -`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. |
9 | | - |
10 | | -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. |
11 | | - |
12 | | -<br> |
13 | | - |
14 | | -## 🐛 **Did you find a bug?** |
15 | | - |
16 | | -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 ( ❗ ). |
17 | | - |
18 | | -_Our track is always a work in progress!_ 🌟🌟 |
19 | | -Please 📛 [Open an issue][open-an-issue] 📛 , and let us know what you have found or suggest. |
20 | | - |
21 | | -<br> |
22 | | - |
23 | | -## 🚧 **Did you write a patch that fixes a bug?** |
24 | | - |
25 | | - 💛 💙 **We Warmly Welcome Pull Requests that are:** |
26 | | - |
27 | | - 1️⃣ Small, contained fixes for typos/grammar/punctuation/code syntax on [one] exercise, |
28 | | - 2️⃣ Medium changes that have been agreed/discussed via a filed issue, |
29 | | - 3️⃣ Contributions from our [help wanted][help-wanted] issue list, |
30 | | - 4️⃣ Larger (_and previously agreed-upon_) contributions from recent & regular (_within the last 6 months_) contributors. |
31 | | - |
32 | | -When in doubt, 📛 [Open an issue][open-an-issue] 📛. We will happily discuss your proposed change. 🐍 |
33 | | - |
34 | | -But let's talk before you take a whole lot of time or energy implementing anything. |
35 | | - |
36 | | -<br> |
37 | | - |
38 | | -## :books: **Want to jump directly into Exercism specifications & detail?** |
39 | | - |
40 | | -✨ 🦄 Here is the good stuff: |
41 | | - |
42 | | -[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] |
43 | | - |
44 | | -Web-formatted 🕸️ versions are available in the [contributing section][website-contributing-section] of exercsim.org. |
45 | | - |
46 | | -<br> |
47 | | - |
48 | | -## 🌍 The Exercism Community 🌏 |
49 | | - |
50 | | -<br> |
51 | | - |
52 | | -🌟🌟 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. |
53 | | -It might also be helpful to take a look at [The words that we use][the-words-that-we-use]. |
54 | | - |
55 | | - |
56 | | -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] |
57 | | - |
58 | | -<br> |
59 | | - |
60 | | -## In General |
61 | | - |
62 | | -<br> |
63 | | - |
64 | | -- Maintainers are happy to review your work and help you. 💛 💙 |
65 | | - - 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. |
66 | | - - **Please wait at least 72 hours before pinging.** |
67 | | -- If you'd like in-progress feedback or discussion, please mark your Pull Request as a `[draft]` |
68 | | -- Pull requests should be focused on a single exercise, issue, or change. |
69 | | -- Pull Request titles and descriptions should make clear **what** has changed and **why**. |
70 | | - - Please link 🔗 to any related issues the PR addresses. |
71 | | -- 📛 [Open an issue][open-an-issue] 📛 and discussed _**before**_ creating a Pull Request making significant or breaking changes to an existing exercise. |
72 | | - - The same rule holds true for changes across multiple exercises. |
73 | | - - It is best to discuss changes with 🧰 maintainers before doing a lot of work. |
74 | | -- Follow coding standards found in [PEP8][PEP8] (["For Humans" version here][pep8-for-humans]). |
75 | | - - We do have some more specific requirements. More on that a little later. |
76 | | -- 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. |
77 | | -- Otherwise, watch out ⚠️ for trailing spaces, extra blank lines, extra spaces, and spaces in blank lines. |
78 | | -- The CI is going to run **a lot** of checks on your PR. Pay attention to the failures, try to understand and fix them. |
79 | | - - If you need help, comment in the PR or issue. 🙋🏽♀️ The maintainers are happy to help troubleshoot. |
80 | | - |
81 | | - |
82 | | - ⚠️ **Before committing** ⚠️ |
83 | | - |
84 | | -- Run `configlet fmt` and `configlet lint` if the track [config.json](config-json) has been modified. |
85 | | -- Run [Prettier][prettier] on all markdown files. |
86 | | -- Run [flake8][flake8] to ensure all Python code files conform to general code style standards. |
87 | | -- Run [???] to help format your code |
88 | | -- Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly. |
89 | | -- Run the `example.py` or `exemplar.py` file against the test file to ensure that it passes without error. |
90 | | -- If you modified or created a `hints.md` file for a practice exercise, [regenerate](#generating-exercise-readmes) it. |
91 | | - |
92 | | -<br> |
93 | | - |
94 | | -## 📄 A Little More on Prose Writing Style and Standards |
95 | | - |
96 | | -<br> |
97 | | - |
98 | | -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]. |
99 | | - |
100 | | -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. |
101 | | - |
102 | | -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]. ✨ |
103 | | - |
104 | | - |
105 | | -<br> |
106 | | - |
107 | | -## Little More on Coding Standards |
108 | | -<br> |
109 | | - |
110 | | - |
111 | | -<br> |
112 | | - |
113 | | -## 🏋️ A Little More on Exercises 🏋🏽♀️ |
114 | | - |
115 | | -- 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. |
116 | | - |
117 | | -- Each exercise/problem should include a complete test suite, an example/exemplar solution, and a stub file ready for student implementation. |
118 | | - |
119 | | - - See [Concept Exercise Anatomy][concept-exercise-anatomy], or [Practice Exercise Anatomy][practice-exercise-anatomy] depending on which type of exercise you are contributing to. |
120 | | - |
121 | | - <details> |
122 | | - <summary>Concept Exercise Checklist</summary>> |
123 | | - </details> |
124 | | - |
125 | | - <br> |
126 | | - |
127 | | - <details> |
128 | | - <summary>Practice Exercise Checklist</summary>> |
129 | | - </details> |
130 | | - |
131 | | -- **Practice exercise**, descriptions and instructions come from a centralized, cross-track [problem specifications][problem-specifications] repository. |
132 | | - |
133 | | - - Any updates or changes need to be proposed/approved in `problem-specifications` first. |
134 | | - - 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. |
135 | | - |
136 | | -- 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]. |
137 | | - - 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. |
138 | | - - 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 | | - |
140 | | - |
141 | | -<br> |
142 | | - |
143 | | - |
144 | | -<br> |
145 | | - |
146 | | -## Python Versions |
147 | | - |
148 | | -<br> |
149 | | - |
150 | | -This track officially supports Python >= `3.8` The track `test runner`, `analyzer`, and `representer` run in docker on `python:3.9-slim`. |
151 | | - |
152 | | -Although the majority of test cases are written using `unittest.TestCase`, |
153 | | - |
154 | | -* All exercises should be written for compatibility with Python >= `3.8`,. |
155 | | -* 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. |
156 | | - |
157 | | -* _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. |
158 | | - |
159 | | -- 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. |
160 | | - |
161 | | -<br> |
162 | | - |
163 | | -## External Libraries and Dependencies |
164 | | - |
165 | | -<br> |
166 | | -<br> |
167 | | - |
168 | | - |
169 | | - |
170 | | -## Auto-Generated Test Files and Test Templates |
171 | | - |
172 | | -<br> |
173 | | - |
174 | | -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 . |
175 | | - |
176 | | -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. |
177 | | - |
178 | | -If a practice exercise has an auto-generated `<exercise>_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. |
179 | | - |
180 | | -Practice exercise `<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. |
181 | | - |
182 | | -<br> |
183 | | - |
184 | | -## Tools and Tooling |
185 | | - |
186 | | - |
187 | | -################################## |
188 | | ->>>>>>> Formatting Update |
| 7 | +- [Contributing Guide](#contributing-guide) |
| 8 | + * [Architecture](#architecture) |
| 9 | + * [Implementing an exercise](#implementing-an-exercise) |
| 10 | + + [Exercise structure](#exercise-structure) |
| 11 | + + [Generating Exercise READMEs](#generating-exercise-readmes) |
| 12 | + - [Requirements](#requirements) |
| 13 | + - [Generating all READMEs](#generating-all-readmes) |
| 14 | + - [Generating a single README](#generating-a-single-readme) |
| 15 | + + [Implementing tests](#implementing-tests) |
| 16 | + + [Example solutions](#example-solutions) |
| 17 | + + [config.json](#configjson) |
| 18 | + * [Implementing Track-specific Exercises](#implementing-track-specific-exercises) |
| 19 | + * [Pull Request Tips](#pull-request-tips) |
189 | 20 |
|
190 | 21 |
|
191 | 22 | ## Architecture |
@@ -316,40 +147,18 @@ Fields |
316 | 147 | 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. |
317 | 148 |
|
318 | 149 |
|
| 150 | +## Pull Request Tips |
319 | 151 |
|
320 | | -[EOL]: https://en.wikipedia.org/wiki/Newline |
321 | | -[PEP8]: https://www.python.org/dev/peps/pep-0008/ |
322 | | -[american-english]: https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md |
323 | | -[being-a-good-community-member]: https://github.com/exercism/docs/tree/main/community/good-member |
324 | | -[concept-exercise-anatomy]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md |
325 | | -[concept-exercises]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md |
326 | | -[config-json]: https://github.com/exercism/javascript/blob/main/config.json |
327 | | -[configlet-general]: https://github.com/exercism/configlet |
328 | | -[configlet]: https://github.com/exercism/docs/blob/main/building/configlet/generating-documents.md |
329 | | -[exercise-presentation]: https://github.com/exercism/docs/blob/main/building/tracks/presentation.md |
330 | | -[exercism-admins]: https://github.com/exercism/docs/blob/main/community/administrators.md |
331 | | -[exercism-code-of-conduct]: https://exercism.org/docs/using/legal/code-of-conduct |
332 | | -[exercism-concepts]: https://github.com/exercism/docs/blob/main/building/tracks/concepts.md |
333 | | -[exercism-contributors]: https://github.com/exercism/docs/blob/main/community/contributors.md |
334 | | -[exercism-internal-linking]: https://github.com/exercism/docs/blob/main/building/markdown/internal-linking.md |
335 | | -[exercism-markdown-specification]: https://github.com/exercism/docs/blob/main/building/markdown/markdown.md |
336 | | -[exercism-markdown-widgets]: https://github.com/exercism/docs/blob/main/building/markdown/widgets.md |
337 | | -[exercism-mentors]: https://github.com/exercism/docs/tree/main/mentoring |
338 | | -[exercism-tasks]: https://exercism.org/docs/building/product/tasks |
339 | | -[exercism-track-maintainers]: https://github.com/exercism/docs/blob/main/community/maintainers.md |
340 | | -[exercism-track-structure]: https://github.com/exercism/docs/tree/main/building/tracks |
341 | | -[exercism-website]: https://exercism.org/ |
342 | | -[exercism-writing-style]: https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md |
343 | | -[flake8]: http://flake8.pycqa.org/ |
344 | | -[help-wanted]: https://github.com/exercism/python/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22 |
345 | | -[markdown-language]: https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf |
346 | | -[open-an-issue]: https://github.com/exercism/python/issues/new/choose |
347 | | -[pep8-for-humans]: https://pep8.org/ |
348 | | -[practice-exercise-anatomy]: https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md |
349 | | -[practice-exercises]: https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md |
350 | | -[prettier]: https://prettier.io/ |
| 152 | +Before committing: |
| 153 | +- Run `configlet fmt` and `configlet lint` before committing if [`config.json`](config.json) has been modified |
| 154 | +- Run [flake8] to ensure all Python code conforms to style standards |
| 155 | +- Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly |
| 156 | +- If you modified or created a `hints.md` file, [regenerate the README](#generating-exercise-readmes) |
| 157 | +- If your changes affect multiple exercises, try to break them up into a separate PR for each exercise. |
| 158 | + |
| 159 | + |
| 160 | +[configlet]: https://github.com/exercism/configlet |
| 161 | +[Exercism contributing guide]: https://github.com/exercism/docs/blob/master/contributing-to-language-tracks/README.md |
351 | 162 | [problem-specifications]: https://github.com/exercism/problem-specifications |
352 | | -[python-syllabus]: https://exercism.org/tracks/python/concepts |
353 | | -[python-track-test-generator]: https://github.com/exercism/python/blob/main/docs/GENERATOR.md |
354 | | -[the-words-that-we-use]: https://github.com/exercism/docs/blob/main/community/good-member/words.md |
355 | | -[website-contributing-section]: https://exercism.org/docs/building |
| 163 | +[topics list]: https://github.com/exercism/problem-specifications/blob/master/TOPICS.txt |
| 164 | +[flake8]: http://flake8.pycqa.org/ |
0 commit comments