|
| 1 | +# How to contribute |
| 2 | + |
| 3 | + |
| 4 | +## Formatting |
| 5 | + |
| 6 | +All entries should be formatted using the `Ctr-D` shortcut for both Lazarus and Delphi entries. |
| 7 | + |
| 8 | +## Folder name for the entry |
| 9 | + |
| 10 | +As mentioned on the `REAME.md` file, the name of the folder for the entry should be composed of your first initial followed by your preferred last name. |
| 11 | + |
| 12 | +For example, using _Gustavo Carreno_ for the name, the folder would be `entries/gcarreno`. |
| 13 | + |
| 14 | +## Name of the executable binary |
| 15 | + |
| 16 | +The executable binary follows the same rules has the entry folder above. |
| 17 | + |
| 18 | +## Placement of the executable binary |
| 19 | + |
| 20 | +The executable binary should be placed under a folder named `bin` below the root folder of this repository. |
| 21 | + |
| 22 | +This folder is not present on the repository and is being ignored from the `.gitignore`. |
| 23 | + |
| 24 | +## Commit Messages |
| 25 | + |
| 26 | +(Originally from the [Udacity Git Commit Message Style Guide](https://udacity.github.io/git-styleguide/index.html)) |
| 27 | + |
| 28 | +### Message Structure |
| 29 | + |
| 30 | +A commit messages consists of three distinct parts separated by a blank line: the title, an optional body and an optional footer. |
| 31 | + |
| 32 | +The layout looks like this: |
| 33 | +``` |
| 34 | +type: subject |
| 35 | +
|
| 36 | +body |
| 37 | +
|
| 38 | +footer |
| 39 | +``` |
| 40 | + |
| 41 | +The title consists of the type of the message and subject. |
| 42 | + |
| 43 | +### The Type |
| 44 | + |
| 45 | +The type is contained within the title and can be one of these types: |
| 46 | + |
| 47 | +* feat: a new feature |
| 48 | +* fix: a bug fix |
| 49 | +* docs: changes to documentation |
| 50 | +* style: formatting, missing semi colons, etc; no code change |
| 51 | +* refactor: refactoring production code |
| 52 | +* test: adding tests, refactoring test; no production code change |
| 53 | +* chore: updating build tasks, package manager configs, etc; no production code change |
| 54 | + |
| 55 | +### The Subject |
| 56 | + |
| 57 | +Subjects should be no greater than 50 characters, should begin with a capital letter and do not end with a period. |
| 58 | + |
| 59 | +Use an imperative tone to describe what a commit does, rather than what it did. For example, use change; not changed or changes. |
| 60 | +The Body |
| 61 | + |
| 62 | +Not all commits are complex enough to warrant a body, therefore it is optional and only used when a commit requires a bit of explanation and context. Use the body to explain the what and why of a commit, not the how. |
| 63 | + |
| 64 | +When writing a body, the blank line between the title and the body is required and you should limit the length of each line to no more than 72 characters. |
| 65 | + |
| 66 | +### The Footer |
| 67 | + |
| 68 | +The footer is optional and is used to reference issue tracker IDs. |
| 69 | + |
| 70 | +### Example Commit Message |
| 71 | + |
| 72 | +``` |
| 73 | +feat: Summarise changes in around 50 characters or less |
| 74 | +
|
| 75 | +More detailed explanatory text, if necessary. Wrap it to about 72 |
| 76 | +characters or so. In some contexts, the first line is treated as the |
| 77 | +subject of the commit and the rest of the text as the body. The |
| 78 | +blank line separating the summary from the body is critical (unless |
| 79 | +you omit the body entirely); various tools like `log`, `shortlog` |
| 80 | +and `rebase` can get confused if you run the two together. |
| 81 | +
|
| 82 | +Explain the problem that this commit is solving. Focus on why you |
| 83 | +are making this change as opposed to how (the code explains that). |
| 84 | +Are there side effects or other non intuitive consequences of this |
| 85 | +change? Here's the place to explain them. |
| 86 | +
|
| 87 | +Further paragraphs come after blank lines. |
| 88 | +
|
| 89 | + - Bullet points are okay, too |
| 90 | +
|
| 91 | + - Typically a hyphen or asterisk is used for the bullet, preceded |
| 92 | + by a single space, with blank lines in between, but conventions |
| 93 | + vary here |
| 94 | +
|
| 95 | +If you use an issue tracker, put references to them at the bottom, |
| 96 | +like this: |
| 97 | +
|
| 98 | +Resolves: #123 |
| 99 | +See also: #456, #789 |
| 100 | +``` |
0 commit comments