Merge branch 'master' of https://github.com/kotorkovsciy/J0kes43oo

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

CONTRIBUTING.md

@@ -0,0 +1,114 @@
+# Contributing guidelines
+
+## Before contributing
+
+Welcome to [kotorkovsciy/J0kes43oo](https://github.com/kotorkovsciy/J0kes43oo)! Before sending your pull requests, make sure that you __read the whole guidelines__. If you have any doubt on the contributing guide, please feel free to [state it clearly in an issue](https://github.com/kotorkovsciy/J0kes43oo/issues/new)
+## Contributing
+
+### Contributor
+
+I are very happy that you consider implementing algorithms and data structures for others! Being one of our contributors, you agree and confirm that:
+
+- You did your work - no plagiarism allowed
+  - Any plagiarized work will not be merged.
+- Your work will be distributed under [AGPL-3.0 license](https://github.com/kotorkovsciy/J0kes43oo/blob/master/LICENSE) once your pull request is merged
+- Your submitted work fulfils or mostly fulfils my styles and standards
+
+__New implementation__ is welcome! For example, new solutions for a problem, different representations for a graph data structure or algorithm designs with different complexity but __identical implementation__ of an existing implementation is not allowed. Please check whether the solution is already implemented or not before submitting your pull request.
+
+__Improving comments__ and __writing proper tests__ are also highly welcome.
+
+
+#### What is an Algorithm?
+
+An Algorithm is one or more functions (or classes) that:
+* take one or more inputs,
+* perform some internal calculations or data manipulations,
+* return one or more outputs,
+* have minimal side effects (Ex. `print()`, `plot()`, `read()`, `write()`).
+
+Algorithms should be packaged in a way that would make it easy for readers to put them into larger programs.
+
+Algorithms should:
+* have intuitive class and function names that make their purpose clear to readers
+* use Python naming conventions and intuitive variable names to ease comprehension
+* be flexible to take different input values
+* have Python type hints for their input parameters and return values
+* raise Python exceptions (`ValueError`, etc.) on erroneous input values
+* have docstrings with clear explanations and/or URLs to source materials
+* contain doctests that test both valid and erroneous input values
+* return all calculation results instead of printing or plotting them
+
+#### Pre-commit plugin
+Use [pre-commit](https://pre-commit.com/#installation) to automatically format your code to match our coding style:
+
+```bash
+python3 -m pip install pre-commit  # only required the first time
+pre-commit install
+```
+That's it! The plugin will run every time you commit any changes. If there are any errors found during the run, fix them and commit those changes. You can even run the plugin manually on all files:
+
+```bash
+pre-commit run --all-files --show-diff-on-failure
+```
+
+#### Coding Style
+
+I want your work to be readable by others; therefore, i encourage you to note the following:
+
+- Please write in Python 3.9+. For instance:  `print()` is a function in Python 3 so `print "Hello"` will *not* work but `print("Hello")` will.
+- Please focus hard on the naming of functions, classes, and variables.  Help your reader by using __descriptive names__ that can help you to remove redundant comments.
+  - Single letter variable names are *old school* so please avoid them unless their life only spans a few lines.
+  - Expand acronyms because `gcd()` is hard to understand but `greatest_common_divisor()` is not.
+  - Please follow the [Python Naming Conventions](https://pep8.org/#prescriptive-naming-conventions) so variable_names and function_names should be lower_case, CONSTANTS in UPPERCASE, ClassNames should be CamelCase, etc.
+
+- I encourage the use of Python [f-strings](https://realpython.com/python-f-strings/#f-strings-a-new-and-improved-way-to-format-strings-in-python) where they make the code easier to read.
+
+- Please consider running [__psf/black__](https://github.com/python/black) on your Python file(s) before submitting your pull request.  This is not yet a requirement but it does make your code more readable and automatically aligns it with much of [PEP 8](https://www.python.org/dev/peps/pep-0008/). There are other code formatters (autopep8, yapf) but the __black__ formatter is now hosted by the Python Software Foundation. To use it,
+
+  ```bash
+  python3 -m pip install black  # only required the first time
+  black .
+  ```
+
+- Original code submission require docstrings or comments to describe your work.
+
+- More on docstrings and comments:
+
+  If you used a Wikipedia article or some other source material to create your algorithm, please add the URL in a docstring or comment to help your reader.
+
+  The following are considered to be bad and may be requested to be improved:
+
+  ```python
+  x = x + 2	# increased by 2
+  ```
+
+  This is too trivial. Comments are expected to be explanatory. For comments, you can write them above, on or below a line of code, as long as you are consistent within the same piece of code.
+
+  I encourage you to put docstrings inside your functions but please pay attention to the indentation of docstrings. The following is a good example:
+
+  ```python
+  def sum_ab(a, b):
+      """
+      Return the sum of two integers a and b.
+      """
+      return a + b
+  ```
+
+- [__List comprehensions and generators__](https://docs.python.org/3/tutorial/datastructures.html#list-comprehensions) are preferred over the use of `lambda`, `map`, `filter`, `reduce` but the important thing is to demonstrate the power of Python in code that is easy to read and maintain.
+
+- Avoid importing external libraries for basic algorithms. Only use those libraries for complicated algorithms.
+- If you need a third-party module that is not in the file __requirements.txt__, please add it to that file as part of your submission.
+
+#### Other Requirements for Submissions
+- Strictly use snake_case (underscore_separated) in your file_name, as it will be easy to parse in future using scripts.
+- Please avoid creating new directories if at all possible. Try to fit your work into the existing directory structure.
+- If possible, follow the standard *within* the folder you are submitting to.
+- If you have modified/added code work, make sure the code compiles before submitting.
+- If you have modified/added documentation work, ensure your language is concise and contains no grammar errors.
+
+- Most importantly,
+  - __Be consistent in the use of these guidelines when submitting.__
+  - Happy coding!
+
+Writer [@kotorkovsciy](https://github.com/kotorkovsciy), July 2022.