|
1 | | -# Contribution guidelines |
| 1 | +# Contribution Guidelines |
2 | 2 |
|
3 | | -First of all, thank you for contributing to our project! This kind of act is the most welcome act to help us keep running our projects the way we want them to run. All your contributions are valuable, but you need to follow these simple rules to get your contribution accepted. |
4 | | - |
5 | | -In the pull requests, we might ask you to make a few changes until we can accept them. If there's no reason for us to add your changes to the project, we might reject them altogether. |
6 | | - |
7 | | -## Following templates |
8 | | - |
9 | | -Your pull requests should follow the template. |
10 | | - |
11 | | -You should be descriptive about what your change is trying to do and what's your opinion about how it affects the whole project. Moreover, it's vital to test your changes before trying to start a pull request to ensure that there are no problems in your initial version. **Always** draft your pull requests. |
12 | | - |
13 | | -## Windows compatibility |
14 | | - |
15 | | -*This doesn't apply to projects that don't use C# or aren't exclusive to Windows.* |
16 | | - |
17 | | -When contributing changes to any part of the code, especially when creating files, your pull requests should follow the below requirements: |
18 | | - |
19 | | - - File names should not contain forbidden characters, such as `/ \ : * ? " < > |`, and control characters, such as a new line, as files with such names don't sit well with Windows. |
20 | | - - File names should always be treated as case sensitive, even if *nix systems allow you to create files with same name but different casing, as files that fall into this category don't sit well with Windows. |
21 | | - - When creating shell scripts in Windows, you should give it executable permissions with `git update-index --chmod=+x <SHELLSCRIPT>` prior to committing, as Windows in general has no concept of Unix permissions. |
22 | | - - In general, make sure that any of your changes don't cause incompatibilities with Windows in any way in both build-time and run-time. |
23 | | - |
24 | | -## Code guidelines |
25 | | - |
26 | | -When it comes to coding your changes, they should follow the below coding guidelines to retain the style of our projects' code. These are the below code guidelines: |
27 | | - |
28 | | -### Sorting of Fields and Properties |
29 | | - |
30 | | -Fields must come at the very beginning of each class before the properties. Between the fields and the properties and the functions, there should be an empty line. Moreover, accesibility modifiers should be sorted in the following order: |
31 | | - |
32 | | -``` |
33 | | -ClassName |
34 | | - | |
35 | | - |-> Public Fields |
36 | | - |-> Public Read-Only Fields |
37 | | - |-> Internal Fields |
38 | | - |-> Private Fields |
39 | | - |-> Internal Read-Only Fields |
40 | | - |-> Private Read-Only Fields |
41 | | - | |
42 | | - |-> Public Properties |
43 | | - |-> Internal Properties (rare, unless you treat them like C #macros) |
44 | | - | |
45 | | -(...) |
46 | | -``` |
47 | | - |
48 | | -### Sorting of Functions |
49 | | - |
50 | | -Sorting of functions is only affected by their accessibility modifiers in your code. Public functions must come before internal functions, at which the private functions come last. |
51 | | - |
52 | | -``` |
53 | | -(...) |
54 | | - | |
55 | | - |-> Public Functions |
56 | | - |-> Internal Functions |
57 | | - |-> Private Functions |
58 | | - | |
59 | | - --- |
60 | | -``` |
61 | | - |
62 | | -### Arrangement of logic in functions |
63 | | - |
64 | | -Inside functions, the arrangement of logic must be in the below order. Moreover, each part of the logic in each function must be preceded by a comment that explains why is your logic is here and a couple of necessary variables before actual logic. |
65 | | - |
66 | | -``` |
67 | | -ClassName |
68 | | -(...) |
69 | | - | |
70 | | - |-> FunctionName(int arg1, string arg2, ...) |
71 | | - | | |
72 | | - | |-> Comment explaining why (not what) is this logic here |
73 | | - | |-> A couple of necessary variables (optional) |
74 | | - | |-> Actual function logic |
75 | | - | | |
76 | | - | (...) |
77 | | - | |
78 | | -(...) |
79 | | -``` |
80 | | - |
81 | | -Example: |
82 | | - |
83 | | -``` |
84 | | -private static void PollForResize() |
85 | | -{ |
86 | | -(...) |
87 | | - // We need to call the WindowHeight and WindowWidth properties on the Terminal console driver, because |
88 | | - // this polling works for all the terminals. Other drivers that don't use the terminal may not even |
89 | | - // implement these two properties. |
90 | | - if (CurrentWindowHeight != termDriver.WindowHeight | CurrentWindowWidth != termDriver.WindowWidth) |
91 | | - { |
92 | | - ResizeDetected = true; |
93 | | -(...) |
94 | | -} |
95 | | -``` |
96 | | - |
97 | | -### Tabs versus Spaces |
98 | | - |
99 | | -Here we come to the argument of tabs vs spaces. Our problem with tabs is that there are systems that treat tabs as four spaces, and there are systems that treat tabs as eight spaces. Moreover, there is no universal way to accurately query the operating system for tab lengths, as such queries are up to the application handling tabs. |
100 | | - |
101 | | -We recommend that you set your IDE to use **four spaces** for each tab press. Also, don't use literal tab characters for indentation (`\t`); use four spaces. |
102 | | - |
103 | | -### Functions that do only one thing |
104 | | - |
105 | | -*This is not applicable to languages that don't support this feature* |
106 | | - |
107 | | -In C#, you can literally make a function without the opening and closing bracelets (`{ }`) if your function only contains one logic. However, you must append `=>` before the logic. Moreover, the logic should be in its own separate line with four spaces as indentation, like the following: |
108 | | - |
109 | | -``` |
110 | | -access_modifier [static] type SingleLogicFunctionName(string arg1, ...) => |
111 | | - MyLogic(arg1, ...).Modify().(...); |
112 | | -``` |
113 | | - |
114 | | -For example, |
115 | | - |
116 | | -``` |
117 | | -public static string[] GetWrappedSentences(string text, int maximumLength) => |
118 | | - GetWrappedSentences(text, maximumLength, 0); |
119 | | -``` |
120 | | - |
121 | | -### If, while, for, foreach statements that do only one thing |
122 | | - |
123 | | -*This is not applicable to languages that don't support this feature* |
124 | | - |
125 | | -In C#, you can literally make an if, while, for, and foreach statements without the opening and closing bracelets (`{ }`) if your statement only contains one logic. However, you must append `=>` before the logic. Moreover, the logic should be in its own separate line with four spaces as indentation, like the following: |
126 | | - |
127 | | -``` |
128 | | -if/while/for/foreach (...) |
129 | | - MyLogicToDo(); |
130 | | -``` |
131 | | - |
132 | | -For example, |
133 | | - |
134 | | -``` |
135 | | -// Also, compensate the \0 characters |
136 | | -if (text[i] == '\0') |
137 | | - vtSeqCompensate++; |
138 | | -``` |
139 | | - |
140 | | -### Naming of Public vs Internal and Private Components |
141 | | - |
142 | | -The naming must satisfy the following rules: |
143 | | - |
144 | | -* All public functions, properties, and fields must follow the Pascal Case (FunctionName) naming scheme, regardless of their purpose. |
145 | | -* For argument names in public, internal, and private functions, they must be named in the scheme of Camel Case (argumentName). |
146 | | -* Private and internal functions and properties must also follow the Pascal Case naming scheme. |
147 | | -* Private and internal fields must use the Camel Case naming style. |
148 | | -* Pascal Case should be used in class names at all times. |
149 | | -* You may never use the snake_case naming (this isn't Rust) or the kebab-case naming scheme (this isn't HTML) in all the components. |
150 | | - |
151 | | -To learn more about Pascal Case and Camel Case, visit [this site](https://www.freecodecamp.org/news/snake-case-vs-camel-case-vs-pascal-case-vs-kebab-case-whats-the-difference/). |
152 | | - |
153 | | -## Git commits |
154 | | - |
155 | | -We follow this conventional Git commit scheme: |
156 | | - |
157 | | -``` |
158 | | -Type - Attributes - Summary |
159 | | -
|
160 | | ---- |
161 | | -
|
162 | | -Description wrapped with 75 characters word-wise |
163 | | -
|
164 | | ---- |
165 | | -
|
166 | | -Type: Type |
167 | | -Breaking: Yes/No |
168 | | -Doc Required: Yes/No |
169 | | -Backport Required: Yes/No |
170 | | -Part: 1/1 |
171 | | -``` |
172 | | - |
173 | | -For types, you should select exactly one type from the following types: |
174 | | - |
175 | | -* `add`: for additions |
176 | | -* `fix`: for fixes |
177 | | -* `rem`: for removals |
178 | | -* `imp`: for improvements |
179 | | -* `ref`: for refactors |
180 | | -* `upd`: for library updates |
181 | | -* `doc`: for documentation updates |
182 | | -* `dev`: for development checkpoints (version bump, etc.) |
183 | | -* `fin`: for development finish points |
184 | | -* `chg`: for minor changes to previous commits |
185 | | -* `int`: for continuous integration changes |
186 | | -* `bkp`: for backports (an empty commit for cherry-picked commits or a full commit for non-cherry-picked backports) |
187 | | -* `prj`: for project initialization |
188 | | -* `pkg`: for packaging-related changes, such as Debian, PKGBUILD, Flatpak, etc. |
189 | | -* `und`: for other changes that don't apply |
190 | | - |
191 | | -Additionally, attributes are optional and can be specified. Multiple attributes should be separated with the pipe character (`|`). However, there are special cases that you may need to handle when you're committing your changes to your pull request: |
192 | | - |
193 | | -* If documentation is required (i.e. your commit requires documentation on GitBook and you've specified `doc`), change the `Doc Required` part to `Yes`, otherwise, `No`. |
194 | | -* If backport is required (i.e. your commit introduces a fix that needs to be backported to previous version series that don't have a fix), change the `Backport Required` part to `Yes`, otherwise, `No`. |
195 | | -* If this commit includes breaking changes (i.e. you've specified `brk`), change the `Breaking` part to `Yes`, otherwise, `No`. |
196 | | -* If this commit is a part of the commit series, specify `prt` and change the `Part` field where it says `1/1` to the current and the total parts in this format: `current/total`. Total parts must be accurate, the title should stay the same as any former commits in the series, and the current part must not be larger than the total part number. |
197 | | - |
198 | | -These are the attributes we officially support: |
199 | | - |
200 | | -* `brk`: for breaking changes |
201 | | -* `sec`: for security |
202 | | -* `prf`: for performance improvements |
203 | | -* `reg`: for regression fixes |
204 | | -* `doc`: for documentation requirement |
205 | | -* `ptp`: for prototyping |
206 | | -* `prt`: for commit series (PartNum is required) |
207 | | -* `bkp`: for backports |
208 | | - |
209 | | -Take note that if you've set a commit that is a backport, make sure that the type is not one of the following types: |
210 | | - |
211 | | -* Incompatible types with `bkp` |
212 | | - * `rem`: for removals |
213 | | - * `dev`: for development checkpoints (version bump, etc.) |
214 | | - * `fin`: for development finish points |
215 | | -* Incompatible attributes with `bkp` |
216 | | - * `ptp`: for prototyping |
217 | | - * `brk`: for breaking changes |
218 | | - |
219 | | -In addition to that, if you've backported a commit from a different branch or tag, you must specify this stanza directly after the description section, just like this: |
220 | | - |
221 | | -* For tags: |
222 | | - ``` |
223 | | - The following commits or tags are used for this backport: |
224 | | - - D877EC56... [Tag 1] |
225 | | - - C6100AF1... [Tag 2] |
226 | | - ``` |
227 | | -* For backported commits: |
228 | | - ``` |
229 | | - The following commits or tags are used for this backport: |
230 | | - - E3218765... |
231 | | - - FAE890DA7... |
232 | | - - BE2701D2... |
233 | | - ``` |
234 | | -
|
235 | | -If you want to specify a command output, you must specify the output name, the description, the command used, and the output. This is placed directly after the description section and, if it exists, the backported commits section, like this: |
236 | | -
|
237 | | -``` |
238 | | -Output |
239 | | - |
240 | | -List of files |
241 | | - |
242 | | - - ls |
243 | | - |
244 | | -total 151 |
245 | | -drwxr-xr-x 1 Aptivi None 0 Nov 6 12:52 . |
246 | | -drwxr-xr-x 1 Aptivi None 0 Aug 2 09:07 .. |
247 | | --rw-r--r-- 1 Aptivi None 4351 Nov 15 2022 DIR_COLORS |
248 | | -(...) |
249 | | -``` |
250 | | -
|
251 | | -## Releases |
252 | | -
|
253 | | -When planning for a new version, always start the development of the next version by changing the version found in all the relevant files (usually `Directory.Build.props` for C# projects) before starting to push commits that add new features and everything else. When development finishes, before the release tag can be pushed, the `CHANGES` file should be changed to reflect the new release, as long as it follows this convention: |
254 | | -
|
255 | | -``` |
256 | | -Long description of the release |
257 | | - |
258 | | -### Changes |
259 | | - |
260 | | -This release contains a variety of changes, including, but not limited to: |
261 | | - |
262 | | -- `[+]` Added X |
263 | | -- `[*]` Improved Y |
264 | | -- `[-]` Removed Z |
265 | | - |
266 | | -Review the commit history if you want to get a deep insight about the changes. |
267 | | - |
268 | | -### Feedback? |
269 | | - |
270 | | -If you have issues with this version, report to us by [making a new issue ticket](https://github.com/Aptivi/PROJECT/issues/new). |
271 | | - |
272 | | -### Sum hashes |
273 | | - |
274 | | -To verify integrity of your download, compare the SHA256 sum of your downloaded file with the following information: |
275 | | - |
276 | | - |
277 | | -``` |
278 | | -
|
279 | | -Two new lines are applied intentionally so that the hash list gets rendered in a way that you'd expect, because the hash sum list gets populated automatically. Also, the `CHANGES.TITLE` file should be changed to match the version whose development finished but tag not pushed, as long as it follows this format: |
280 | | -
|
281 | | -``` |
282 | | -[servicing] PROJECT v1.0.0: Release Name |
283 | | -``` |
284 | | -
|
285 | | -The type at the beginning is necessary as it can tell us and the users in what stage this release belongs to. Currently, this list of releases should be used: |
286 | | -
|
287 | | - * `alpha`: Indicates that this release is an alpha version |
288 | | - * `beta`: Indicates that this release is a beta version |
289 | | - * `release`: Indicates that this release is a major release (i.e. changes the major part and/or the minor part) |
290 | | - * `servicing`: Indicates that this release is a minor release (i.e. changes the build part and/or the patch part) |
291 | | -
|
292 | | -## Assistance of AI |
293 | | -
|
294 | | -Although artifical intelligence (AI) is a next-gen technology that every company is leaning to, which we are proud of, but when contributing code or other things to this project, we rely on human work to ensure maximum quality. This means that you are not allowed to use any kind of AI assistance to generate code and non-code contributions, such as ChatGPT and others, in fear of licensing issues, potential security issues, and current hallucination issues. Any usage of such tools when contributing will be immediately rejected. |
295 | | -
|
296 | | -## Engagement with the Community |
297 | | -
|
298 | | -Thank you for your contribution to our project, but in order for this contribution to be flawless, you must be respectful to all other developers of the projects and the users in general, regardless of whether there is a fight or a heated discussion going on. Try to keep it civil during fights and don't use personal attacks, threats of any kind, derogatory and racist remarks against people or groups of any race, ethnicity, religion, or group, and explicit words (like swearing) to try to solve any disagreement with anyone, including the developers of the project. |
| 3 | +You can read our contribution guidelines [here](https://aptivi.gitbook.io/aptivi/guidelines/contribution-guidelines). |
0 commit comments