|
| 1 | +# Contributing guidelines |
| 2 | + |
| 3 | +## Before contributing |
| 4 | + |
| 5 | +Welcome to [TheAlgorithms/Nim](https://github.com/TheAlgorithms/Nim)! 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/TheAlgorithms/Nim/issues/new) or ask the community in [Discord](https://discord.gg/c7MnfGFGa6). |
| 6 | + |
| 7 | +## Contributing |
| 8 | + |
| 9 | +### Contributor |
| 10 | + |
| 11 | +We are very happy that you are considering implementing algorithms and data structures for others! This repository is referenced and used by learners from all over the globe. Being one of our contributors, you agree and confirm that: |
| 12 | + |
| 13 | +- You did your work - no plagiarism allowed |
| 14 | + - Any plagiarized work will not be merged. |
| 15 | +- Your work will be distributed under [MIT License](LICENSE.md) once your pull request is merged |
| 16 | +- Your submitted work fulfils or mostly fulfills our styles and standards |
| 17 | + |
| 18 | +__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. |
| 19 | + |
| 20 | +__Improving comments__ and __writing proper tests__ are also highly welcome. |
| 21 | + |
| 22 | +### Contribution |
| 23 | + |
| 24 | +We appreciate any contribution, from fixing a grammar mistake in a comment to implementing complex algorithms. Please read this section if you are contributing your work. |
| 25 | + |
| 26 | +Please help us keep our issue list small by adding fixes: Add the number of the issue you solved — even if only partially — to the commit message of your pull request. GitHub will use this tag to auto-close the issue when the PR is merged. |
| 27 | + |
| 28 | +#### What is an Algorithm? |
| 29 | + |
| 30 | +An Algorithm is one or more functions (or classes) that: |
| 31 | +* take one or more inputs, |
| 32 | +* perform some internal calculations or data manipulations, |
| 33 | +* return one or more outputs, |
| 34 | +* have minimal side effects (Examples of side effects: `print()`, `plot()`, `read()`, `write()`). |
| 35 | + |
| 36 | +Algorithms should be packaged in a way that would make it easy for readers to put them into larger programs. |
| 37 | + |
| 38 | +Algorithms should: |
| 39 | +* have intuitive class and function names that make their purpose clear to readers |
| 40 | +* use Nim naming conventions and intuitive variable names with correct typing to ease comprehension |
| 41 | +* Prefer `Natural` type to `uint` unless wrapping is mandatory (for e.g. modular algorithms). |
| 42 | +* raise Nim exceptions (`ValueError`, etc.) on erroneous input values |
| 43 | +* add the exceptions raised to the list of side effects |
| 44 | +* have docstrings with clear explanations and/or URLs to source materials |
| 45 | +* contain doctests that test both valid and erroneous input values |
| 46 | +* return all calculation results instead of printing or plotting them |
| 47 | + |
| 48 | +Algorithms in this repo should not be how-to examples for existing Nim packages. Instead, they should perform internal calculations or manipulations to convert input values into different output values. Those calculations or manipulations can use objects or functions of existing Nim modules but each algorithm in this repo should add unique value. |
| 49 | + |
| 50 | +#### Coding Style |
| 51 | + |
| 52 | +We want your work to be readable by others; therefore, we encourage you to note the following: |
| 53 | + |
| 54 | +- Please write in Nim 2.0. |
| 55 | +- Please focus hard on the naming of functions, objects, and variables. Help your reader by using __descriptive names__ that can help you to remove redundant comments. |
| 56 | + - Single letter variable names must be avoided at all costs. You can use `index` instead of `i` when iterating in a `for` loop. |
| 57 | + - Expand acronyms because `gcd()` is hard to understand (especially for non-native English people) but `greatest_common_divisor()` is not. |
| 58 | + - Please follow the [Nim Naming Conventions](https://nim-lang.org/docs/nep1.html) so variable names and function names should be camelCase while object names should be PascalCase. |
| 59 | + |
| 60 | +- Avoid importing external libraries for basic algorithms. Only use those libraries for complicated algorithms. |
| 61 | +- If you need a third-party module that is not in the file [third_party_modules.md](https://github.com/TheAlgorithms/Nim/blob/master/third_party_modules.md), please add it to that file as part of your submission. |
| 62 | + |
| 63 | +#### Other Requirements for Submissions |
| 64 | +The file extension for code files should be `.nim`. |
| 65 | +- Strictly use snake_case (underscore_separated) in your file_name, as it will be easy to parse in future using scripts. |
| 66 | +- Please open an issue first if you want to create a new directory. Try to fit your work into the existing directory structure as much as possible. |
| 67 | +- If possible, follow the standard *within* the folder you are submitting to. |
| 68 | +- If you have modified/added code work, make sure the code compiles before submitting. |
| 69 | +- If you have modified/added documentation work, ensure your language is concise and contains no grammar errors. |
| 70 | +- Add a corresponding explanation to [Algorithms-Explanation](https://github.com/TheAlgorithms/Algorithms-Explanation) (Optional but recommended). |
| 71 | + |
| 72 | +- Most importantly, |
| 73 | + - __Be consistent in the use of these guidelines when submitting.__ |
| 74 | + - __Join__ us on [Discord](https://discord.gg/c7MnfGFGa6) __now!__ |
| 75 | + - Happy coding! |
| 76 | + |
| 77 | +Writer [@dlesnoff](https://github.com/dlesnoff), Mar 2023. |
0 commit comments