mirror of https://github.com/TheAlgorithms/C
[feat/fix]: Add contributing guidelines and update templates (#610)
* feat: Add contributing guidelines * fix: Use the correct links in PR/issue template * fix: Update README.md to point to correct links * fix: Update README.md * fix: Move contributing guidelines to root directory * fix: Update PR template
This commit is contained in:
David Leal
GitHub
parent
4cb3eeb1af
commit
544f492720
|
|
@ -24,6 +24,7 @@ assignees: ''
|
|||
## Steps to Reproduce
|
||||
<!--- Provide a link to a live example, or an unambiguous set of steps to -->
|
||||
<!--- reproduce this bug. Include code to reproduce, if relevant -->
|
||||
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
|
|
|
|||
|
|
@ -1,9 +1,10 @@
|
|||
#### Description of Change
|
||||
|
||||
<!--
|
||||
Thank you for your Pull Request. Please provide a description above and review
|
||||
the requirements below.
|
||||
|
||||
Contributors guide: https://github.com/TheAlgorithms/C-Plus-Plus/CONTRIBUTING.md
|
||||
Contributors guide: https://github.com/TheAlgorithms/C/blob/master/CONTRIBUTING.md
|
||||
-->
|
||||
|
||||
#### References
|
||||
|
|
@ -13,10 +14,10 @@ Contributors guide: https://github.com/TheAlgorithms/C-Plus-Plus/CONTRIBUTING.md
|
|||
<!-- Remove items that do not apply. For completed items, change [ ] to [x]. -->
|
||||
|
||||
- [ ] Added description of change
|
||||
- [ ] Added file name matches [File name guidelines](https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/CONTRIBUTING.md#New-File-Name-guidelines)
|
||||
- [ ] Added file name matches [File name guidelines](https://github.com/TheAlgorithms/C/blob/master/CONTRIBUTING.md#File-Name-guidelines)
|
||||
- [ ] Added tests and example, test must pass
|
||||
- [ ] Relevant documentation/comments is changed or added
|
||||
- [ ] PR title follows semantic [commit guidelines](https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/CONTRIBUTING.md#Commit-Guidelines)
|
||||
- [ ] PR title follows semantic [commit guidelines](https://github.com/TheAlgorithms/C/blob/master/CONTRIBUTING.md#Commit-Guidelines)
|
||||
- [ ] Search previous suggestions before making a new one, as yours may be a duplicate.
|
||||
- [ ] I acknowledge that all my contributions will be made under the project's license.
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,227 @@
|
|||
# CONTRIBUTION GUIDELINES
|
||||
|
||||
## Before contributing
|
||||
|
||||
Welcome to [TheAlgorithms/C](https://github.com/TheAlgorithms/C)! Before submitting pull requests, please make sure that you have **read the whole guidelines**. If you have any doubts about this contribution guide, please open [an issue](https://github.com/TheAlgorithms/C/issues/new/choose) and clearly state your concerns.
|
||||
|
||||
## Contributing
|
||||
|
||||
### Maintainer/developer
|
||||
|
||||
If you are a maintainer of this repository, please consider the following:
|
||||
|
||||
- It is a protocol to contribute via pull requests.
|
||||
- Reviewers will advise and guide you up to make the code refined and documented.
|
||||
- When reviewing pull requests, be sure to:
|
||||
- Be kind.
|
||||
- Be respectful.
|
||||
- Make useful suggestions/comments.
|
||||
- Be sure not to make invalid suggestions/comments.
|
||||
- Guide and advise up the pull request author.
|
||||
|
||||
### Contributor
|
||||
|
||||
We are very happy that you consider implementing algorithms and data structures for others! This repository is referred to and used by learners from around the globe. Being one of our contributors, you agree and confirm that:
|
||||
|
||||
- You did your own work.
|
||||
- No plagiarism allowed. Any plagiarized work will not be merged.
|
||||
- Your work will be distributed under the [GNU General Public License v3.0](https://github.com/TheAlgorithms/C/blob/master/LICENSE) once your pull request has been merged.
|
||||
- You submitted work fulfils or mostly fulfils our styles and standards.
|
||||
|
||||
**New implementation** New implementation are welcome!
|
||||
|
||||
**Improving comments** and **adding tests** to existing algorithms are much appreciated.
|
||||
|
||||
**Issues** Please avoid opening issues asking to be "assigned” to a particular algorithm. This merely creates unnecessary noise for maintainers. Instead, please submit your implementation in a pull request and it will be evaluated by project maintainers.
|
||||
|
||||
### Making Changes
|
||||
|
||||
#### Code
|
||||
|
||||
- Please use the directory structure of the repository.
|
||||
- File extension for code should be `*.h` `*.c`
|
||||
- Organize your code using **`struct`** keywords
|
||||
- If an implementation of the algorithm already exists, please refer to the [file-name section below](#file-name-guidelines).
|
||||
- You can suggest reasonable changes to existing algorithms.
|
||||
- Strictly use snake_case (underscore_separated) in filenames.
|
||||
- If you have added or modified code, please make sure the code compiles before submitting.
|
||||
- Our automated testing runs [__CMake__](https://cmake.org/) on all pull requests so please be sure that your code passes before submitting.
|
||||
- Please conform to [doxygen](https://www.doxygen.nl/manual/docblocks.html) standard and document the code as much as possible. This not only facilitates the readers but also generates the correct info on website.
|
||||
- **Be consistent in use of these guidelines.**
|
||||
|
||||
#### Documentation
|
||||
|
||||
- Make sure you put useful comments in your code. Do not comment things that are obvious.
|
||||
- Please avoid creating new directories if at all possible. Try to fit your work into the existing directory structure. If you want to create a new directory, then please check if a similar category has been recently suggested or created by other pull requests.
|
||||
- If you have modified/added documentation, please ensure that your language is concise and contains no grammar errors.
|
||||
- Do not update README.md along with other changes, first create an issue and then link to that issue in your pull request to suggest specific changes required to README.md
|
||||
- The repository follows [Doxygen](https://www.doxygen.nl/manual/docblocks.html) standards and auto-generates the [repository website](https://thealgorithms.github.io/C). Please ensure the code is documented in this structure. Sample implementation is given below.
|
||||
|
||||
#### Test
|
||||
|
||||
- Make sure to add examples and test cases in your main() function.
|
||||
- If you find any algorithm or document without tests, please feel free to create a pull request or issue describing suggested changes.
|
||||
- Please try to add one or more `test()` functions that will invoke the algorithm implementation on random test data with expected output. Use `assert()` function to confirm that the tests will pass. Requires adding the `assert.h` library.
|
||||
|
||||
#### Typical structure of a program
|
||||
|
||||
```c
|
||||
/**
|
||||
* @file
|
||||
* @brief Add one line description here
|
||||
* @details
|
||||
* This is a multi line
|
||||
* description containing links, references,
|
||||
* math equations, etc
|
||||
* @author [Name](https://github.com/handle)
|
||||
* @see related_file.c, another_file.c
|
||||
*/
|
||||
|
||||
#include <assert.h>
|
||||
#include
|
||||
|
||||
/**
|
||||
* @brief Struct documentation
|
||||
*/
|
||||
struct struct_name {
|
||||
int variable; ///< short info of this variable
|
||||
char message; ///< short info
|
||||
};
|
||||
|
||||
/**
|
||||
* Function documentation
|
||||
* @param param1 one-line info about param1
|
||||
* @param param2 one-line info about param2
|
||||
* @returns `true` if ...
|
||||
* @returns `false` if ...
|
||||
*/
|
||||
bool func(int param1, int param2) {
|
||||
// function statements here
|
||||
if (/*something bad*/) {
|
||||
return false;
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Test function
|
||||
* @returns void
|
||||
*/
|
||||
static void test() {
|
||||
/* desciptions of the following test */
|
||||
assert(func(...) == ...); // this ensures that the algorithm works as expected
|
||||
|
||||
// can have multiple checks
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Main function
|
||||
* @returns 0 on exit
|
||||
*/
|
||||
int main() {
|
||||
test(); // execute the tests
|
||||
// code here
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
#### File name guidelines
|
||||
|
||||
- Use lowercase words with ``"_"`` as separator
|
||||
- For instance
|
||||
|
||||
```markdown
|
||||
MyNewCStruct.C is incorrect
|
||||
my_new_c_struct.c is correct format
|
||||
```
|
||||
|
||||
- It will be used to dynamically create a directory of files and implementation.
|
||||
- File name validation will run on docker to ensure the validity.
|
||||
- If an implementation of the algorithm already exists and your version is different from that implemented, please use incremental numeric digit as a suffix. For example, if `median_search.c` already exists in the `search` folder and you are contributing a new implementation, the filename should be `median_search2.c` and for a third implementation, `median_search3.c`.
|
||||
|
||||
#### Directory guidelines
|
||||
|
||||
- We recommend adding files to existing directories as much as possible.
|
||||
- Use lowercase words with ``"_"`` as separator ( no spaces or ```"-"``` allowed )
|
||||
- For instance
|
||||
|
||||
```markdown
|
||||
SomeNew Fancy-Category is incorrect
|
||||
some_new_fancy_category is correct
|
||||
```
|
||||
|
||||
- Filepaths will be used to dynamically create a directory of our algorithms.
|
||||
- Filepath validation will run on GitHub Actions to ensure compliance.
|
||||
|
||||
#### Commit Guidelines
|
||||
|
||||
- It is recommended to keep your changes grouped logically within individual commits. Maintainers find it easier to understand changes that are logically spilt across multiple commits. Try to modify just one or two files in the same directory. Pull requests that span multiple directories are often rejected.
|
||||
|
||||
```bash
|
||||
git add file_xyz.c
|
||||
git commit -m "your message"
|
||||
```
|
||||
|
||||
Examples of commit messages with semantic prefixes:
|
||||
|
||||
```markdown
|
||||
fix: xyz algorithm bug
|
||||
feat: add xyx algorithm, struct xyz
|
||||
test: add test for xyz algorithm
|
||||
docs: add comments and explanation to xyz algorithm
|
||||
```
|
||||
|
||||
Common prefixes:
|
||||
|
||||
- fix: A bug fix
|
||||
- feat: A new feature
|
||||
- docs: Documentation changes
|
||||
- test: Correct existing tests or add new ones
|
||||
|
||||
### Pull Requests
|
||||
|
||||
- Checkout our [pull request template](https://github.com/TheAlgorithms/C/blob/master/.github/pull_request_template.md)
|
||||
|
||||
#### Building Locally
|
||||
|
||||
Before submitting a pull request, build the code locally or using the convenient [](https://gitpod.io/#https://github.com/TheAlgorithms/C) service.
|
||||
|
||||
```bash
|
||||
cmake -B build -S .
|
||||
```
|
||||
|
||||
#### Static Code Analyzer
|
||||
|
||||
We use [clang-tidy](https://clang.llvm.org/extra/clang-tidy/) as a static code analyzer with a configuration in [.clang-tidy](.clang-tidy).
|
||||
|
||||
```bash
|
||||
clang-tidy --fix --quiet -p build subfolder/file_to_check.c --
|
||||
```
|
||||
|
||||
#### Code Formatter
|
||||
|
||||
[__clang-format__](https://clang.llvm.org/docs/ClangFormat.html) is used for code forrmating.
|
||||
|
||||
- Installation (only needs to be installed once.)
|
||||
- Mac (using home-brew): `brew install clang-format`
|
||||
- Mac (using macports): `sudo port install clang-10 +analyzer`
|
||||
- Windows (MSYS2 64-bit): `pacman -S mingw-w64-x86_64-clang-tools-extra`
|
||||
- Linux (Debian): `sudo apt-get install clang-format-10 clang-tidy-10`
|
||||
- Running (all platforms): `clang-format -i -style="file" my_file.c`
|
||||
|
||||
#### GitHub Actions
|
||||
|
||||
- Enable GitHub Actions on your fork of the repository.
|
||||
After enabling it will execute `clang-tidy` and `clang-format` after every a push (not a commit).
|
||||
- Click on the tab "Actions", then click on the big green button to enable it.
|
||||
|
||||
|
||||
|
||||
- The result can create another commit if the actions made any changes on your behalf.
|
||||
- Hence, it is better to wait and check the results of GitHub Actions after every push.
|
||||
- Run `git pull` in your local clone if these actions made many changes in order to avoid merge conflicts.
|
||||
|
||||
Most importantly,
|
||||
|
||||
- Happy coding!
|
||||
|
|
@ -2,23 +2,23 @@
|
|||
<!-- the suffix in the above line is required for doxygen to consider this as the index page of the generated documentation site -->
|
||||
|
||||
[](https://gitpod.io/#https://github.com/TheAlgorithms/C)
|
||||
[](https://lgtm.com/projects/g/TheAlgorithms/C/context:cpp)
|
||||
[](https://lgtm.com/projects/g/TheAlgorithms/C/context:cpp)
|
||||
[](https://gitter.im/TheAlgorithms)
|
||||
[](https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/CONTRIBUTING.md)
|
||||
[](https://github.com/TheAlgorithms/C/blob/master/CONTRIBUTING.md)
|
||||
|
||||
[](https://TheAlgorithms.github.io/C)
|
||||
[](https://github.com/TheAlgorithms/C/actions?query=workflow%3A%22Awesome+CI+Workflow%22)
|
||||
|
||||
## Overview
|
||||
|
||||
The repository is a collection of open-source implementation of a variety of algorithms implemented in C and licensed under [GPLv3 License](https://github.com/TheAlgorithms/C/blob/master/LICENSE). The algorithms span a variety of topics from computer science, mathematics and statistics, data science, machine learning, engineering, etc.. The implementations and the associated documentation are meant to provide a learning resource for educators and students. Hence, one may find more than one implementation for the same objective but using a different algorithm strategies and optimizations.
|
||||
The repository is a collection of open-source implementation of a variety of algorithms implemented in C and licensed under [GPLv3 License](https://github.com/TheAlgorithms/C/blob/master/LICENSE). The algorithms span a variety of topics from computer science, mathematics and statistics, data science, machine learning, engineering, etc.. The implementations and the associated documentation are meant to provide a learning resource for educators and students. Hence, one may find more than one implementation for the same objective but using a different algorithm strategies and optimizations.
|
||||
|
||||
## Features
|
||||
|
||||
* The repository provides implementations of various algorithms in one of the most fundamental general purpose languages - [C](https://en.wikipedia.org/wiki/C_(programming_language)).
|
||||
* Well documented source code with detailed explanations provide a valuable resource for educators and students alike.
|
||||
* Each source code is atomic using standard C library [`libc`](https://en.wikipedia.org/wiki/C_standard_library) and _no external libraries_ are required for their compilation and execution. Thus the fundamentals of the algorithms can be studied in much depth.
|
||||
* Source codes are [compiled and tested](https://github.com/TheAlgorithms/C/actions?query=workflow%3A%22Awesome+CI+Workflow%22) for every commit on the latest versions of three major operating systems viz., Windows, MacOS and Ubuntu (Linux) using MSVC 16 2019, AppleClang 11.0 and GNU 7.5.0 respectively.
|
||||
* Source codes are [compiled and tested](https://github.com/TheAlgorithms/C/actions?query=workflow%3A%22Awesome+CI+Workflow%22) for every commit on the latest versions of three major operating systems viz., Windows, MacOS and Ubuntu (Linux) using MSVC 16 2019, AppleClang 11.0 and GNU 7.5.0 respectively.
|
||||
* Strict adherence to [C11](https://en.wikipedia.org/wiki/C11_(C_standard_revision)) standard ensures portability of code to embedded systems as well like ESP32, ARM Cortex, etc. with little to no changes.
|
||||
* Self-checks within programs ensure correct implementations with confidence.
|
||||
* Modular implementations and OpenSource licensing enable the functions to be utilized conveniently in other applications.
|
||||
|
|
|
|||
Loading…
Reference in New Issue