|
| 1 | +# Contributing guidelines |
| 2 | + |
| 3 | +## Before contributing |
| 4 | + |
| 5 | +Welcome to [TheAlgorithms/TypeScript](https://github.com/TheAlgorithms/TypeScript)! Before sending your pull requests, |
| 6 | +make sure that you **read the whole guidelines**. If you have any doubt on the contributing guide, please feel free to |
| 7 | +[state it clearly in an issue](https://github.com/TheAlgorithms/TypeScript/issues/new) or on our [**Discord server**](https://discord.gg/c7MnfGFGa6). |
| 8 | + |
| 9 | +## Contributing |
| 10 | + |
| 11 | +### Contributor |
| 12 | + |
| 13 | +We are very happy that you consider implementing algorithms and data structures for others! This repository is |
| 14 | +referenced and used by learners from around the globe. Being one of our contributors, you agree and confirm that: |
| 15 | + |
| 16 | +- You did your work - plagiarism is not allowed. |
| 17 | + - Any plagiarized work will not be merged. |
| 18 | +- Your work will be distributed under [MIT License](LICENSE) once your pull request is merged. |
| 19 | +- Your submitted work must fulfill our styles and standards. |
| 20 | + |
| 21 | +**New implementations** are welcome! For example, new solutions to a problem, different representations of a graph data |
| 22 | +structure, or algorithm designs with different complexity. |
| 23 | + |
| 24 | +**Improving comments** and **writing proper tests** are also highly welcome. |
| 25 | + |
| 26 | +### Contribution |
| 27 | + |
| 28 | +We appreciate any contribution, from fixing grammar mistakes to implementing complex algorithms. Please read this |
| 29 | +section if you are contributing to this repository. |
| 30 | + |
| 31 | +If you submit a pull request that resolves an open issue, please help us to keep our issue list small by adding |
| 32 | +`closes: #{$ISSUE_NO}` to your commit message. GitHub will use this tag to auto-close the issue if your PR is merged. |
| 33 | + |
| 34 | +#### What is an Algorithm? |
| 35 | + |
| 36 | +An Algorithm is one or more functions (or classes) that: |
| 37 | + |
| 38 | +- Take one or more inputs. |
| 39 | +- Perform some internal calculations or data manipulations. |
| 40 | +- Return one or more outputs. |
| 41 | +- Have minimal side effects. |
| 42 | + |
| 43 | +Algorithms should be packaged in a way that would make it easy for readers to put them into larger programs. |
| 44 | + |
| 45 | +Algorithms should: |
| 46 | + |
| 47 | +- Have intuitive class and function names that make their purpose clear to readers. |
| 48 | +- Use TypeScript naming conventions and intuitive variable names to ease comprehension. |
| 49 | +- Be flexible to take different input values. |
| 50 | +- Raise TypeScript exceptions (RangeError, etc.) on erroneous input values. |
| 51 | + |
| 52 | +Algorithms in this repo should not be how-to examples for existing TypeScript packages. Instead, they should perform |
| 53 | +internal calculations or manipulations to convert input values into different output values. Those calculations or |
| 54 | +manipulations can use data types, classes, or functions of existing TypeScript packages but each algorithm in this repo |
| 55 | +should add unique value. |
| 56 | + |
| 57 | +#### File Naming Convention |
| 58 | + |
| 59 | +- Filenames should use the UpperCamelCase (PascalCase) style. |
| 60 | +- There should be no spaces in filenames. |
| 61 | +- **Example:** `UserProfile.ts` is allowed. Do not use `userprofile.ts`, `Userprofile.ts`, `user-Profile.ts`, `userProfile.ts`; these naming conventions are discouraged. |
| 62 | + |
| 63 | +#### Commit Messages Formatting |
| 64 | + |
| 65 | +- Prefer to use the following format: `<type>: <short summary>`. If necessary, put any extra information in the description. |
| 66 | +- Commit types include (but are not limited to): |
| 67 | + - **docs**: Documentation only changes |
| 68 | + - **feat**: A new feature |
| 69 | + - **fix**: A bug fix |
| 70 | + - **test**: Adding or fixing tests |
| 71 | + - **chore**: CI / code quality / minor quality of life improvements |
| 72 | + |
| 73 | +- **Examples**: |
| 74 | + - `feat: add quicksort algorithm` |
| 75 | + - `chore: fix spelling` |
| 76 | + - `fix: improper error message` |
| 77 | + - `docs: add contributing guidelines` |
| 78 | + - `test: add test for quicksort algorithm` |
| 79 | + |
| 80 | +#### Module System |
| 81 | + |
| 82 | +We use the [ES Module](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/) system, which brings an official, standardized module system to TypeScript. |
| 83 | + |
| 84 | +It roughly means you will need to use `export` and `import` statements instead of `module.exports` and `require()`. |
| 85 | + |
| 86 | +#### Coding Style |
| 87 | + |
| 88 | +To maximize the readability and correctness of our code, we require that new submissions follow the |
| 89 | +[TypeScript Standard Style](https://github.com/standard/ts-standard). |
| 90 | + |
| 91 | +A few (but not all) of the things to keep in mind: |
| 92 | + |
| 93 | +- Naming conventions: |
| 94 | + - Names always start with a letter (not with an underscore). |
| 95 | + - Use `UpperCamelCase` for classes, interfaces & types. |
| 96 | + - Use `lowerCamelCase` for functions and local variables. |
| 97 | + - Use `SCREAMING_SNAKE_CASE` for global ("universal") constants. |
| 98 | +- Code indentation: Always use 2 spaces for indentation of code blocks. |
| 99 | + |
| 100 | +```ts |
| 101 | +function sum(arr: number[]): number { |
| 102 | + let total = 0; |
| 103 | + for (const elem of arr) total += elem; |
| 104 | + return total; |
| 105 | +} |
| 106 | +``` |
| 107 | + |
| 108 | +- Avoid using global variables and avoid `==` (use `===` instead). |
| 109 | +- Use only `let` and `const`, never use `var` |
| 110 | +- Prefer proper input/output of your functions over side effects. |
| 111 | +- We required the use of TypeScript. |
| 112 | +- Only use `any` if appropriate. Prefer to create proper types instead. |
| 113 | +- No redundant naming. Don't prefix interfaces with `I`, class members with `m`, function with `func` or `f`, etc. |
| 114 | +- Prefer using optional fields over `null` or `undefined`. |
| 115 | + |
| 116 | +```ts |
| 117 | +// BAD |
| 118 | +let foo = { x: 123, y: undefined }; |
| 119 | + |
| 120 | +// GOOD |
| 121 | +let foo: { x: number, y?: number } = { x: 123 }; |
| 122 | +``` |
| 123 | + |
| 124 | +- Annotate arrays as `foos: Foo[]` instead of `foos: Array<Foo>`. |
| 125 | +- Refrain from importing external libraries. Implement the algorithms "from scratch". |
| 126 | +- Most importantly: |
| 127 | + - **Be consistent in the use of these guidelines when submitting.** |
| 128 | + - Happy coding! |
0 commit comments