From cc704cebb4ca8f31c1ccbaf9b229a6be47de3c1a Mon Sep 17 00:00:00 2001 From: Vadim Nifadev <36514612+nifadyev@users.noreply.github.com> Date: Sun, 24 Nov 2024 15:01:40 +0300 Subject: [PATCH 1/3] #269: Update CONTRIBUTING guidelines, add PR and issue templates - Add issue templates for bugs, translations and new snippets - Add PR templates for general purpose, new snippets and translations --- .github/ISSUE_TEMPLATE/bug.md | 25 ++++++++++ .github/ISSUE_TEMPLATE/new_snippet.md | 23 ++++++++++ .github/ISSUE_TEMPLATE/translation.md | 13 ++++++ .github/PULL_REQUEST_TEMPLATE/new_snippet.md | 15 ++++++ .../pull_request_template.md | 13 ++++++ .github/PULL_REQUEST_TEMPLATE/translation.md | 13 ++++++ CONTRIBUTING.md | 46 ++++++++++--------- 7 files changed, 126 insertions(+), 22 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug.md create mode 100644 .github/ISSUE_TEMPLATE/new_snippet.md create mode 100644 .github/ISSUE_TEMPLATE/translation.md create mode 100644 .github/PULL_REQUEST_TEMPLATE/new_snippet.md create mode 100644 .github/PULL_REQUEST_TEMPLATE/pull_request_template.md create mode 100644 .github/PULL_REQUEST_TEMPLATE/translation.md diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md new file mode 100644 index 0000000..0e7241e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.md @@ -0,0 +1,25 @@ +--- +name: Bug report +about: Bug template +title: 'Fix ...' +labels: 'bug' + +--- + + +## What's wrong + + + +## How it should work? + + + +## Checklist before calling for maintainers + +* [ ] Have you checked to ensure there aren't other open [Issues](../../../issues) for the same problem? + diff --git a/.github/ISSUE_TEMPLATE/new_snippet.md b/.github/ISSUE_TEMPLATE/new_snippet.md new file mode 100644 index 0000000..09b045a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/new_snippet.md @@ -0,0 +1,23 @@ +--- +name: New snippet +about: New snippet template +title: 'New snippet: ...' +labels: 'new snippets' +--- + + +## Description + +## Snippet preview + +## Checklist before calling for maintainers + +* [ ] Have you checked to ensure there aren't other open [Issues](../../../issues) for the same update/change? +* [ ] Have you checked that this snippet is not similar to any of the existing snippets? + +* [ ] Have you added an `Explanation` section? It shall include the reasons of changes and why you'd like us to include them + diff --git a/.github/ISSUE_TEMPLATE/translation.md b/.github/ISSUE_TEMPLATE/translation.md new file mode 100644 index 0000000..788bc4c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/translation.md @@ -0,0 +1,13 @@ +--- +name: Translation +about: New translation template +title: 'Tranlate to ...' +labels: 'translations' + +--- + + +## Checklist before calling for maintainers + +* [ ] Have you checked to ensure there aren't other open [Issues](../../../issues) for the same tranlation? +* [ ] Do you wish to make a translation by yourself? diff --git a/.github/PULL_REQUEST_TEMPLATE/new_snippet.md b/.github/PULL_REQUEST_TEMPLATE/new_snippet.md new file mode 100644 index 0000000..5d10e7f --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/new_snippet.md @@ -0,0 +1,15 @@ +## #(issue number): Summarize your changes + + + +Closes # (issue number) + +## Checklist before requesting a review + +- [ ] Have you written simple and understandable explanation? +- [ ] Have you added new snippet into `snippets/` with suitable name and number? +- [ ] Have you updated Table of content? (later will be done by pre-commit) +- [ ] Have you followed the guidelines in [CONTRIBUTING.md](../../CONTRIBUTING.md)? +- [ ] Have you performed a self-review? +- [ ] Have you added yourself into [CONTRIBUTORS.md](../../CONTRIBUTORS.md)? diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md new file mode 100644 index 0000000..155780d --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md @@ -0,0 +1,13 @@ +## #(issue number): Summarize your changes + + + +Closes # (issue number) + +## Checklist before requesting a review + +- [ ] Have you followed the guidelines in [CONTRIBUTING.md](../../CONTRIBUTING.md)? +- [ ] Have you performed a self-review? +- [ ] Have you added yourself into [CONTRIBUTORS.md](../../CONTRIBUTORS.md)? + diff --git a/.github/PULL_REQUEST_TEMPLATE/translation.md b/.github/PULL_REQUEST_TEMPLATE/translation.md new file mode 100644 index 0000000..990a389 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/translation.md @@ -0,0 +1,13 @@ +## #(issue number): Translate to ... + + + +Closes # (issue number) + +## Checklist before requesting a review + +- [ ] Have you fetched the latest `master` branch? +- [ ] Have you translated all snippets? +- [ ] Have you followed the guidelines in [CONTRIBUTING.md](../../CONTRIBUTING.md)? +- [ ] Have you performed a self-review? +- [ ] Have you added yourself into [CONTRIBUTORS.md](../../CONTRIBUTORS.md)? diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dd9049d..771ece8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,19 @@ +# Contributing + +## Getting Started + +Contributions are made to this repo via Issues and Pull Requests (PRs). A few general guidelines that cover both: + +- Search for existing Issues and PRs before creating your own. +- We work hard to makes sure issues are handled in a timely manner but, depending on the impact, it could take a while to investigate the root cause. A friendly ping in the comment thread to the submitter or a contributor can help draw attention if your issue is blocking. + +## Issues + All kinds of patches are welcome. Feel free to even suggest some catchy and funny titles for the existing Examples. The goal is to make this collection as interesting to read as possible. Here are a few ways through which you can contribute, -- If you are interested in translating the project to another language (some people have done that in the past), please feel free to open up an issue, and let me know if you need any kind of help. +- If you are interested in translating the project to another language, please feel free to open up an issue using `translation` template, and let me know if you need any kind of help. - If the changes you suggest are significant, filing an issue before submitting the actual patch will be appreciated. If you'd like to work on the issue (highly encouraged), you can mention that you're interested in working on it while creating the issue and get assigned to it. -- If you're adding a new example, it is highly recommended to create an issue to discuss it before submitting a patch. You can use the following template for adding a new example: +- If you're adding a new example, it is highly recommended to create an issue using `new_snippet` template to discuss it before submitting a patch. You can use the following template for adding a new example: 
 ### ▶ Some fancy Title *
@@ -33,31 +44,22 @@ Probably unexpected output
 ```
+## Pull requests -Few things that you can consider while writing an example, - -- If you are choosing to submit a new example without creating an issue and discussing, please check the project to make sure there aren't similar examples already. - Try to be consistent with the namings and the values you use with the variables. For instance, most variable names in the project are along the lines of `some_string`, `some_list`, `some_dict`, etc. You'd see a lot of `x`s for single letter variable names, and `"wtf"` as values for strings. There's no strictly enforced scheme in the project as such, but you can take a glance at other examples to get a gist. - Try to be as creative as possible to add that element of "surprise" in the setting up part of an example. Sometimes this may mean writing a snippet a sane programmer would never write. - Also, feel free to add your name to the [contributors list](/CONTRIBUTORS.md). -**Some FAQs** +## Common questions - What is is this after every snippet title (###) in the README: ? Should it be added manually or can it be ignored when creating new snippets? - -That's a random UUID, it is used to keep identify the examples across multiple translations of the project. As a contributor, you don't have to worry about behind the scenes of how it is used, you just have to add a new random UUID to new examples in that format. - - Where should new snippets be added? Top/bottom of the section, doesn't ? - -There are multiple things that are considered to decide the order (the dependency on the other examples, difficulty level, category, etc). I'd suggest simply adding the new example at the bottom of a section you find more fitting (or just add it to the Miscellaneous section). Its order will be taken care of in future revisions. - - What's the difference between the sections (the first two feel very similar)? - -The section "Strain your brain" contains more contrived examples that you may not really encounter in real life, whereas the section "Slippery Slopes" contains examples that have the potential to be encountered more frequently while programming. - - Before the table of contents it says that markdown-toc -i README.md --maxdepth 3 was used to create it. The pip package markdown-toc does not contain either -i or --maxdepth flags. Which package is meant, or what version of that package? - Should the new table of contents entry for the snippet be created with the above command or created manually (in case the above command does more than only add the entry)? - -We use the [markdown-toc](https://www.npmjs.com/package/markdown-toc) npm package to generate ToC. It has some issues with special characters though (I'm not sure if it's fixed yet). More often than not, I just end up inserting the toc link manually at the right place. The tool is handy when I have to big reordering, otherwise just updating toc manually is more convenient imo. +- What is is this after every snippet title (###) in the README: ? Should it be added manually or can it be ignored when creating new snippets? + - That's a random UUID, it is used to keep identify the examples across multiple translations of the project. As a contributor, you don't have to worry about behind the scenes of how it is used, you just have to add a new random UUID to new examples in that format. +- Where should new snippets be added? Top/bottom of the section, doesn't ? +- There are multiple things that are considered to decide the order (the dependency on the other examples, difficulty level, category, etc). I'd suggest simply adding the new example at the bottom of a section you find more fitting (or just add it to the Miscellaneous section). Its order will be taken care of in future revisions. +- What's the difference between the sections (the first two feel very similar)? + - The section "Strain your brain" contains more contrived examples that you may not really encounter in real life, whereas the section "Slippery Slopes" contains examples that have the potential to be encountered more frequently while programming. +- Before the table of contents it says that `markdown-toc -i README.md --maxdepth 3` was used to create it. The pip package `markdown-toc` does not contain neither `-i` nor `--maxdepth` flags. Which package is meant, or what version of that package? Should the new table of contents entry for the snippet be created with the above command or created manually (in case the above command does more than only add the entry)? + - `markdown-toc` will be replaced in the near future, follow the [issue](https://github.com/satwikkansal/wtfpython/issues/351) to check the progress. + - We use the [markdown-toc](https://www.npmjs.com/package/markdown-toc) npm package to generate ToC. It has some issues with special characters though (I'm not sure if it's fixed yet). More often than not, I just end up inserting the toc link manually at the right place. The tool is handy when I have to big reordering, otherwise just updating toc manually is more convenient imo. If you have any questions feel free to ask on [this issue](https://github.com/satwikkansal/wtfpython/issues/269) (thanks to [@LiquidFun](https://github.com/LiquidFun) for starting it). From 84e757692b54ae805656652438670c4c54ba9c81 Mon Sep 17 00:00:00 2001 From: Vadim Nifadev <36514612+nifadyev@users.noreply.github.com> Date: Tue, 26 Nov 2024 09:10:27 +0300 Subject: [PATCH 2/3] #269: Change issues link and fix typos in Github issue templates --- .github/ISSUE_TEMPLATE/bug.md | 4 ++-- .github/ISSUE_TEMPLATE/new_snippet.md | 8 ++++---- .github/ISSUE_TEMPLATE/translation.md | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md index 0e7241e..2162d31 100644 --- a/.github/ISSUE_TEMPLATE/bug.md +++ b/.github/ISSUE_TEMPLATE/bug.md @@ -1,6 +1,6 @@ --- name: Bug report -about: Bug template +about: Report a problem and provide necessary context title: 'Fix ...' labels: 'bug' @@ -21,5 +21,5 @@ But, we will need some information about what's wrong to help you. ## Checklist before calling for maintainers -* [ ] Have you checked to ensure there aren't other open [Issues](../../../issues) for the same problem? +* [ ] Have you checked to ensure there aren't other open [Issues](../../issues) for the same problem? diff --git a/.github/ISSUE_TEMPLATE/new_snippet.md b/.github/ISSUE_TEMPLATE/new_snippet.md index 09b045a..47fc83c 100644 --- a/.github/ISSUE_TEMPLATE/new_snippet.md +++ b/.github/ISSUE_TEMPLATE/new_snippet.md @@ -1,6 +1,6 @@ --- name: New snippet -about: New snippet template +about: Suggest new gotcha and try to explain it title: 'New snippet: ...' labels: 'new snippets' --- @@ -16,8 +16,8 @@ But, we will need some information and (optionally) explanation to accept it. ## Checklist before calling for maintainers -* [ ] Have you checked to ensure there aren't other open [Issues](../../../issues) for the same update/change? +* [ ] Have you checked to ensure there aren't other open [Issues](../../issues) for the same update/change? * [ ] Have you checked that this snippet is not similar to any of the existing snippets? - -* [ ] Have you added an `Explanation` section? It shall include the reasons of changes and why you'd like us to include them + +* [ ] Have you added an `Explanation` section? It shall include the reasons for changes and why you'd like us to include them diff --git a/.github/ISSUE_TEMPLATE/translation.md b/.github/ISSUE_TEMPLATE/translation.md index 788bc4c..e80b731 100644 --- a/.github/ISSUE_TEMPLATE/translation.md +++ b/.github/ISSUE_TEMPLATE/translation.md @@ -1,7 +1,7 @@ --- name: Translation -about: New translation template -title: 'Tranlate to ...' +about: Request a new traslation and start working on it (if possible) +title: 'Translate to ...' labels: 'translations' --- @@ -9,5 +9,5 @@ labels: 'translations' ## Checklist before calling for maintainers -* [ ] Have you checked to ensure there aren't other open [Issues](../../../issues) for the same tranlation? +* [ ] Have you checked to ensure there aren't other open [Issues](../../issues) for the same translation? * [ ] Do you wish to make a translation by yourself? From 684650beec732dd1024cbcb105a4a9b3b73add3c Mon Sep 17 00:00:00 2001 From: Vadim Nifadev <36514612+nifadyev@users.noreply.github.com> Date: Tue, 26 Nov 2024 16:05:18 +0300 Subject: [PATCH 3/3] Rename common PR template, fix links in PR and issue templates --- .github/ISSUE_TEMPLATE/bug.md | 2 +- .github/ISSUE_TEMPLATE/new_snippet.md | 2 +- .github/ISSUE_TEMPLATE/translation.md | 2 +- .../{pull_request_template.md => common.md} | 4 ++-- .github/PULL_REQUEST_TEMPLATE/new_snippet.md | 4 ++-- .github/PULL_REQUEST_TEMPLATE/translation.md | 4 ++-- 6 files changed, 9 insertions(+), 9 deletions(-) rename .github/PULL_REQUEST_TEMPLATE/{pull_request_template.md => common.md} (69%) diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md index 2162d31..2cfa777 100644 --- a/.github/ISSUE_TEMPLATE/bug.md +++ b/.github/ISSUE_TEMPLATE/bug.md @@ -21,5 +21,5 @@ But, we will need some information about what's wrong to help you. ## Checklist before calling for maintainers -* [ ] Have you checked to ensure there aren't other open [Issues](../../issues) for the same problem? +* [ ] Have you checked to ensure there aren't other open [Issues](../issues) for the same problem? diff --git a/.github/ISSUE_TEMPLATE/new_snippet.md b/.github/ISSUE_TEMPLATE/new_snippet.md index 47fc83c..6bb19dc 100644 --- a/.github/ISSUE_TEMPLATE/new_snippet.md +++ b/.github/ISSUE_TEMPLATE/new_snippet.md @@ -16,7 +16,7 @@ But, we will need some information and (optionally) explanation to accept it. ## Checklist before calling for maintainers -* [ ] Have you checked to ensure there aren't other open [Issues](../../issues) for the same update/change? +* [ ] Have you checked to ensure there aren't other open [Issues](../issues) for the same update/change? * [ ] Have you checked that this snippet is not similar to any of the existing snippets? * [ ] Have you added an `Explanation` section? It shall include the reasons for changes and why you'd like us to include them diff --git a/.github/ISSUE_TEMPLATE/translation.md b/.github/ISSUE_TEMPLATE/translation.md index e80b731..37ea4c3 100644 --- a/.github/ISSUE_TEMPLATE/translation.md +++ b/.github/ISSUE_TEMPLATE/translation.md @@ -9,5 +9,5 @@ labels: 'translations' ## Checklist before calling for maintainers -* [ ] Have you checked to ensure there aren't other open [Issues](../../issues) for the same translation? +* [ ] Have you checked to ensure there aren't other open [Issues](../issues) for the same translation? * [ ] Do you wish to make a translation by yourself? diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/common.md similarity index 69% rename from .github/PULL_REQUEST_TEMPLATE/pull_request_template.md rename to .github/PULL_REQUEST_TEMPLATE/common.md index 155780d..ab9f34a 100644 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ b/.github/PULL_REQUEST_TEMPLATE/common.md @@ -7,7 +7,7 @@ Closes # (issue number) ## Checklist before requesting a review -- [ ] Have you followed the guidelines in [CONTRIBUTING.md](../../CONTRIBUTING.md)? +- [ ] Have you followed the guidelines in [CONTRIBUTING.md](../CONTRIBUTING.md)? - [ ] Have you performed a self-review? -- [ ] Have you added yourself into [CONTRIBUTORS.md](../../CONTRIBUTORS.md)? +- [ ] Have you added yourself into [CONTRIBUTORS.md](../CONTRIBUTORS.md)? diff --git a/.github/PULL_REQUEST_TEMPLATE/new_snippet.md b/.github/PULL_REQUEST_TEMPLATE/new_snippet.md index 5d10e7f..dab5816 100644 --- a/.github/PULL_REQUEST_TEMPLATE/new_snippet.md +++ b/.github/PULL_REQUEST_TEMPLATE/new_snippet.md @@ -10,6 +10,6 @@ Closes # (issue number) - [ ] Have you written simple and understandable explanation? - [ ] Have you added new snippet into `snippets/` with suitable name and number? - [ ] Have you updated Table of content? (later will be done by pre-commit) -- [ ] Have you followed the guidelines in [CONTRIBUTING.md](../../CONTRIBUTING.md)? +- [ ] Have you followed the guidelines in [CONTRIBUTING.md](../CONTRIBUTING.md)? - [ ] Have you performed a self-review? -- [ ] Have you added yourself into [CONTRIBUTORS.md](../../CONTRIBUTORS.md)? +- [ ] Have you added yourself into [CONTRIBUTORS.md](../CONTRIBUTORS.md)? diff --git a/.github/PULL_REQUEST_TEMPLATE/translation.md b/.github/PULL_REQUEST_TEMPLATE/translation.md index 990a389..74f8800 100644 --- a/.github/PULL_REQUEST_TEMPLATE/translation.md +++ b/.github/PULL_REQUEST_TEMPLATE/translation.md @@ -8,6 +8,6 @@ Closes # (issue number) - [ ] Have you fetched the latest `master` branch? - [ ] Have you translated all snippets? -- [ ] Have you followed the guidelines in [CONTRIBUTING.md](../../CONTRIBUTING.md)? +- [ ] Have you followed the guidelines in [CONTRIBUTING.md](../CONTRIBUTING.md)? - [ ] Have you performed a self-review? -- [ ] Have you added yourself into [CONTRIBUTORS.md](../../CONTRIBUTORS.md)? +- [ ] Have you added yourself into [CONTRIBUTORS.md](../CONTRIBUTORS.md)?