10000 Update CONTRIBUTING.md · runtimehub-com/algorithms-mojo@83edbd7 · GitHub
[go: up one dir, main page]
Skip to content

Commit 83edbd7

Browse files
SatinWukerORIGSatinWukerORIG
authored
Update CONTRIBUTING.md
1 parent 9a1b06f commit 83edbd7

File tree

1 file changed

+109
-1
lines changed

1 file changed

+109
-1
lines changed

‎CONTRIBUTING.md

+109-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,109 @@
1-
# Contribution Guidelines
1+
# Contributing Guidelines
2+
3+
Welcome to [TheAlgorithms/Mojo](https://github.com/TheAlgorithms/Mojo)!
4+
5+
Welcome to Mojo! This repository is meant to be referenced and used by learners worldwide, and we aspire to maintain the highest possible quality of the code presented here! If you have any questions or concerns about this guide, please feel free to [state them clearly in an issue](https://github.com/TheAlgorithms/Mojo/issues/new) or ask the community in [Discord](https://the-algorithms.com/discord).
6+
7+
## Table Of Contents
8+
9+
* [What is an Algorithm?](#what-is-an-algorithm)
10+
* [Contributor agreement](#contributor-agreement)
11+
* [Contribution guidelines](#contribution-guidelines)
12+
+ [Implementation requirements](#implementation-requirements)
13+
+ [Mojo Coding Style](#Mojo-coding-style)
14+
- [Readability and naming conventions](#readability-and-naming-conventions)
15+
- [Compilation](#compilation)
16+
- [Types](#types)
17+
- [Exceptions and side-effects](#exceptions-and-side-effects)
18+
- [Documentation, examples, and tests](#documentation-examples-and-tests)
19+
- [Other](#other)
20+
+ [Minimal example](#Minimal-example)
21+
+ [Submissions Requirements](#submissions-requirements)
22+
23+
## What is an Algorithm?
24+
25+
An Algorithm is one or more functions that:
26+
27+
- take one or more inputs,
28+
- perform some internal calculations or data manipulations,
29+
- return one or more outputs,
30+
- have minimal side effects (Examples of side effects: `print`, `read`).
31+
32+
## Contributor Agreement
33+
34+
Being one of our contributors, you agree and confirm that:
35+
36+
- Your work will be distributed under [MIT License](LICENSE) once your pull request is merged.
37+
- Your work meets the standards of this guideline.
38+
39+
## Contribution Guidelines
40+
41+
We appreciate any contribution, from fixing a grammar mistake in a comment to implementing complex algorithms. Please check the [directory](DIRECTORY.md) and [issues](https://github.com/TheAlgorithms/Mojo/issues/) for an existing (or declined) implementation of your algorithm and relevant discussions.
42+
43+
**New implementations** are welcome! This includes new solutions for a problem, different representations for a data structure, and algorithm design with different complexity or features.
44+
45+
**Improving documentation and comments** and **adding tests** is also highly welcome.
46+
47+
**Identical implementations** are not allowed.
48+
49+
### Environment
50+
The environment that I am using is `mojo 0.2.1 (64d14e85)` on Ubuntu 20.04.6 LTS.
51+
Installing the SDK is guided by this doc: https://docs.modular.com/mojo/manual/get-started/
52+
53+
### Implementation requirements
54+
55+
- Although the main goals of this repository are educational, the module form mirrors a real-world scenario and makes it easy to use the code from this repository in other projects.
56+
- The first line must contain the canonical title of the module prefixed by double hashes (`## Title Of The Module`). This title is used in this repository's automation for populating the [Directory](DIRECTORY.md).
57+
- The module should be thoroughly documented with comments.
58+
- The file begins with the module-level documentation with the general description and explanation of the algorithm/data-structure:
59+
* Any restrictions of the implementation and any constraints for the input data.
60+
* An overview of the use cases.
61+
* Recommendations for when to use or avoid using it.
62+
* Comparison with the alternatives.
63+
* Links to source materials and further reading.
64+
- Use intuitive and descriptive names for objects, functions, and variables.
65+
- Return all calculation results instead of printing or plotting them.
66+
- Avoid importing third-party libraries. Only use those for complicated algorithms and only if the alternatives of relying on the standard library or including a short amount of the appropriately-licensed external code are not feasible.
67+
### Mojo Coding Style
68+
69+
#### Readability and naming conventions
70+
71+
We want your work to be readable by others; Although there is no naming conventions or best practices of Mojo, Mojo code style can be considered exactly same as Python 3 code style, [PEP 8](https://peps.python.org/pep-0008/).
72+
73+
- Help your readers by using **descriptive names** that eliminate the need for redundant comments.
74+
- Avoid single-letter variable names, unless it has a Minimal lifespan. If your variable comes from a mathematical context or no confusion is possible with another variable, you may use single-letter variables. Generally, single-letter variables stop being OK if there are more than just a couple of them in scope. Some examples:
75+
* Prefer `index` or `idx` than `i` for loops.
76+
* Prefer `src` and `dst` than `a` and `b`.
77+
* Prefer `remainder` than `r` and `prefix` than `p`.
78+
- Expand acronyms. Prefer `greatest_common_divisor()` than `gcd()`, as the former is easier to understand than the latter, especially for non-native English speakers.
79+
80+
### Simple example
81+
82+
```Python
83+
## Algorithm Name
84+
##
85+
## Description + link
86+
87+
## Comment
88+
fn algo(arr):
89+
## Comment
90+
return arr[0] + arr[1]
91+
92+
```
93+
94+
### Submissions Requirements
95+
96+
- Make sure the code compiles before submitting.
97+
- Look up the name of your algorithm in other active repositories of [TheAlgorithms](https://github.com/TheAlgorithms/), like [TheAlgorithms/Python](https://github.com/TheAlgorithms/Python). By reusing the same name, your implementation will be appropriately grouped alongside other implementations on the [project's website](https://the-algorithms.com/).
98+
- 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.
99+
- Use *snake_case* (words separated with an underscore `_`) for the filename.
100+
- Try to fit your work into the existing directory structure as much as possible. Please open an issue first if you want to create a new subdirectory.
101+
- Writing documentation, be concise, and check your spelling and grammar.
102+
- Add a corresponding explanation to [Algorithms-Explanation](https://github.com/TheAlgorithms/Algorithms-Explanation) (optional but recommended).
103+
- Most importantly, **be consistent in the use of these guidelines**.
104+
105+
**Happy coding!**
106+
107+
---
108+
109+
Authors: [@SatinWuker](https://github.com/SatinWuker)

0 commit comments

Comments
 (0)
0