|
2 | 2 |
|
3 | 3 | ## Design Guideline and Pull Requests |
4 | 4 |
|
5 | | -This project follows the following design guidelines, which will continue until the next breaking change of the Swift toolchain or itself. |
| 5 | +This project follows the following design guidelines, which will continue until the next breaking change of the Swift toolchain or itself. |
6 | 6 |
|
7 | | -If you'd like to contribute to the project by implementing a new feature or fixing bugs, make sure your code and API matches them. |
| 7 | +If you'd like to contribute to the project by implementing a new feature or fixing bugs, make sure your code and API matches them. |
8 | 8 |
|
9 | 9 | - **Single-file and lightweight.** Keep it a single-file executable which can be easily installed or use as a script without any config. |
10 | | -- **Specific for platforms excluding macOS.** Apple has already provided a bunch of great Swift tools like `xcrun` on macOS and sometimes Darwin behaves differently from Linux, making Darwin support hard but quite useless. |
11 | | -- **Unaffected by unmanaged environment variables,** which is likely to differ between shells on the same system. The users are assumed to be totally ignorant about environment variables. |
| 10 | +- **Specific for platforms excluding macOS.** Apple has already provided a bunch of great Swift tools like `xcrun` on macOS and sometimes Darwin behaves differently from Linux, making Darwin support hard but quite useless. |
| 11 | +- **Unaffected by unmanaged environment variables,** which is likely to differ between shells on the same system. The users are assumed to be totally ignorant about environment variables. |
12 | 12 | - **Keeping different defaults of system-wide, user-wide and project-wide**(coming at the next version). This allows `sudoer`s to install and configure Swift for its users. |
13 | | -- **Independent of any self-hosted APIs.** Use only official websites and repositories to retrieve package information and the toolchain. |
14 | | -- **Avoiding hard-coded information** like versions. This generally gives the program longer usability, while it can be discussed in specific cases. |
| 13 | +- **Independent of any self-hosted APIs.** Use only official websites and repositories to retrieve package information and the toolchain. |
| 14 | +- **Avoiding hard-coded information** like versions. This generally gives the program longer usability, while it can be discussed in specific cases. |
15 | 15 |
|
16 | | -If you're going to add a new feature or make breaking changes, **you're suggested to make a proposal by creating an issue before starting your implementation**, so that we can discuss about it in advance, making sure your idea is fit for the project. |
| 16 | +If you're going to add a new feature or make breaking changes, **you're suggested to make a proposal by creating an issue before starting your implementation**, so that we can discuss about it in advance, making sure your idea is fit for the project. |
17 | 17 |
|
18 | 18 | ## Commits and Pull Requests Naming Guide |
19 | 19 |
|
20 | 20 | `swiftbox` follows an easy naming guide, which simply contains two rules: |
21 | 21 |
|
22 | | -- Use **a verb phrase or a noun phrase** that describes what this commit or PR has done, and **start with upper case**. |
23 | | -- If there's more than one, remember to concat them like: one, two and three. |
| 22 | +- Use **a verb phrase or a noun phrase** that describes what this commit or PR has done, and **start with upper case**. |
| 23 | +- If there's more than one, remember to concat them like: one, two and three. |
24 | 24 |
|
25 | 25 | Here are some suggested verbs to use: |
26 | 26 |
|
27 | | -- Fix: Always use `Fix` when you fixes a bug; Alternatively, you can use the noun form. |
28 | | -- Add: Always use `Add` when you add a new file or a project-related feature; Sometimes, you can omit `Add` to make the message a nown. |
29 | | -- Support: Always use `Support` when you add a new subcommand or feature to the main program. |
30 | | -- Improve: You are suggested to use `Improve` when you refine the working process of any subcommand or module. |
| 27 | +- Fix: Always use `Fix` when you fixes a bug; Alternatively, you can use the noun form. |
| 28 | +- Add: Always use `Add` when you add a new file or a project-related feature; Sometimes, you can omit `Add` to make the message a nown. |
| 29 | +- Support: Always use `Support` when you add a new subcommand or feature to the main program. |
| 30 | +- Improve: You are suggested to use `Improve` when you refine the working process of any subcommand or module. |
31 | 31 |
|
32 | 32 | ## API Naming Guide |
33 | 33 |
|
34 | 34 | `swiftbox` currently provides an unstable cli. When you design a new API, you simply need to: |
35 | 35 |
|
36 | | -- **Use a verb** instead of a noun (The `version` command is a counter-example which I'm going to refine). |
37 | | -- Use a simple verb, and **imagine you're doing this with a magic box**. |
| 36 | +- **Use a verb** instead of a noun (The `version` command is a counter-example which I'm going to refine). |
| 37 | +- Use a simple verb, and **imagine you're doing this with a magic box**. |
38 | 38 |
|
39 | 39 | ## Coding Style |
40 | 40 |
|
41 | | -Commits of pull requests will be asked to follow the coding (including naming, indentation and line-break) style of the original project. Here're some instructions: |
| 41 | +Commits of pull requests will be asked to follow the coding (including naming, indentation and line-break) style of the original project. Here're some instructions: |
42 | 42 |
|
43 | | -- Use `verb-noun` styled function names, or `is-predicative` ones if the return value is used as a bool result. |
44 | | -- Use `OBJECT` or `ATTRIBUTE_OBJECT` styled variable names. |
45 | | -- Keep variables `local` if possible. |
| 43 | +- Use `verb-noun` styled function names, or `is-predicative` ones if the return value is used as a bool result. |
| 44 | +- Use `OBJECT` or `ATTRIBUTE_OBJECT` styled variable names. |
| 45 | +- Keep variables `local` if possible. |
46 | 46 |
|
47 | 47 | ## About Operating System Supports |
48 | 48 |
|
49 | | -This project is **temporarily** dedicated to officially supported operating systems excluding macOS. If you want to configure it for another platform, welcome to fork as a new one. |
| 49 | +This project is **temporarily** dedicated to officially supported operating systems excluding macOS. If you want to configure it for another platform, welcome to fork as a new one. |
50 | 50 |
|
51 | 51 | Once Swift.org releases installation packages for other distributions, you can support them by creating pull requests. |
0 commit comments