@@ -9,15 +9,15 @@ forms of collaboration as well. [Let's talk!][support] :handshake:
99
1010If you are unsure how to start implementing an idea or fix:
1111
12- - :bug : open an issue, there are human friendly templates for _ bugs_
13- and _ feature requests_ at < https://github.com/kernelkit/infix/issues >
14- - :speech_balloon : use the [ Q&A Forum] [ discuss ]
15- - :technologist : The [ Developer's Guide] [ devguide ] is also a useful start
12+ - :bug : open an issue, there are human friendly templates for _ bugs_
13+ and _ feature requests_ at < https://github.com/kernelkit/infix/issues >
14+ - :speech_balloon : use the [ Q&A Forum] [ discuss ]
15+ - :technologist : The [ Developer's Guide] [ devguide ] is also a useful start
1616
17- > _ Talking about code and problems first is often the best way to get
17+ > [ !IMPORTANT]
18+ > Talking about code and problems first is often the best way to get
1819> started before submitting a pull request. We have found it always
19- > saves time, yours and ours._
20-
20+ > saves time, yours and ours.
2121
2222:sparkles : General Guidelines
2323-----------------------------
@@ -27,21 +27,20 @@ version the change is made against, what it does, and, more importantly
2727* why* -- from your perspective, why is it a bug, why does the code need
2828changing in this way. Start with why.
2929
30- - :bug : Bug reports need metadata like Infix version or commit hash
31- - :adhesive_bandage : Bug fixes also need version, and (preferably) a
32- corresponding issue number for the ChangeLog
33- - :new : New features, you need to get approval of the YANG model first!
34- :speech_balloon : Please use the [ Forum] [ discuss ] , e.g., category:
35- * Ideas* , or open a :pray : feature request issue
36- - :white_check_mark : New features also need new regression tests, this
37- can be basic tests or more complex use-case tests comprising multiple
38- subsystems, see [ Testing Changes] ( #test_tube-testing-changes ) , below
30+ - :bug : Bug reports need metadata like Infix version or commit hash
31+ - :adhesive_bandage : Bug fixes also need version, and (preferably) a
32+ corresponding issue number for the ChangeLog
33+ - :new : New features, you need to get approval of the YANG model first!
34+ :speech_balloon : Please use the [ Forum] [ discuss ] , e.g., category:
35+ * Ideas* , or open a :pray : feature request issue
36+ - :white_check_mark : New features also need new regression tests, this
37+ can be basic tests or more complex use-case tests comprising multiple
38+ subsystems, see [ Testing Changes] ( #test_tube-testing-changes ) , below
3939
4040Please take care to ensure you follow the project coding style and the
4141commit message format. If you follow these recommendations you help
4242the maintainers and make it easier for them to include your code.
4343
44-
4544:woman_technologist : Coding Style
4645---------------------------------
4746
@@ -51,39 +50,40 @@ and it is expected that you provide a human-readable summary for the
5150release notes (ChangeLog) and at least a configuration example in the
5251manual for new features.
5352
54- > ** Tip:** consider [ "Readme driven development"] [ RDD ] for new features.
55- > It is amazing how many flaws in your own bright ideas come to bare
56- > when you suddenly have to explain them to someone else!
53+ > [ !TIP]
54+ > Consider [ "Readme driven development"] [ RDD ] for new features. It is
55+ > amazing how many flaws in your own bright ideas come to bare when you
56+ > suddenly have to explain them to someone else!
5757
5858We expect code contributions for:
5959
60- - C code in [ Linux Coding Style] [ Linux ]
61- - Python code should follow [ PEP-8] [ ]
60+ - C code in [ Linux Coding Style] [ Linux ]
61+ - Python code should follow [ PEP-8] [ ]
6262
63+ > [ !IMPORTANT]
6364> ** However,** always submit code that follows the style of surrounding
6465> code! Legacy takes precedence, and remember, we read code a lot more
6566> than write it, so legibility is important.
6667
6768The ChangeLog deserves a separate mention:
6869
69- - Releases are listed in reverse chronological order order, so the
70- latest/next release is at the beginning of the file
71- - Only * user-facing bugs and features* are detailed, so code refactor,
72- new tests, etc. are not listed.
73- - Add your changes/features to the Changes section
74- - Add your Fix line in the Fixes section, in numeric order
75- - Changes and fixes without an issue number are listed after all
76- numbered ones
77- - YANG model changes are documented in their respective model, for
78- standard models, e.g., for ` ietf-interfaces.yang ` , the corresponding
79- ` infix-interfaces.yang ` detail augments/deviations as revisions.
70+ - Releases are listed in reverse chronological order order, so the
71+ latest/next release is at the beginning of the file
72+ - Only * user-facing bugs and features* are detailed, so code refactor,
73+ new tests, etc. are not listed.
74+ - Add your changes/features to the Changes section
75+ - Add your Fix line in the Fixes section, in numeric order
76+ - Changes and fixes without an issue number are listed after all
77+ numbered ones
78+ - YANG model changes are documented in their respective model, for
79+ standard models, e.g., for ` ietf-interfaces.yang ` , the corresponding
80+ ` infix-interfaces.yang ` detail augments/deviations as revisions.
8081
8182A final note, lines of code are allowed to be longer than 72 characters
8283these days, unless you live by PEP-8 (see above). There is no enforced
8384maximum, but the team usually keep it around 100 characters for both C
8485and Python.
8586
86-
8787:test_tube : Testing Changes
8888---------------------------
8989
@@ -97,9 +97,8 @@ the same pull request.
9797
9898For help getting started with testing, see the following resources:
9999
100- - [ Developer's Guide] [ devguide ]
101- - [ Regression Testing] [ testing ]
102-
100+ - [ Developer's Guide] [ devguide ]
101+ - [ Regression Testing] [ testing ]
103102
104103:memo : Commit Messages
105104----------------------
@@ -110,45 +109,135 @@ proud of your work and set up a proper GIT identity for your commits:
110109
111110<img src =" ../doc/jack.png " width =70 align =" right " >
112111
113- $ git config --global user.name "Jacky Linker"
114- $ git config --global user.email [email protected] 112+ ``` bash
113+ $ git config --global user.name " Jacky Linker"
114+ $ git config --global user.email
[email protected] 115+ ```
115116
116117Example commit message from one of many [ online guides] [ cbeams ] . Use
117118` git commit -s ` to automatically add a ` Signed-off-by ` for proof of
118119origin, see [ DCO] [ ] for more info.
119120
120- subsystem: brief, but clear and concise summary of changes
121-
122- More detailed explanatory text, if necessary. Wrap it to about 72
123- characters or so. In some contexts, the first line is treated as
124- the subject of an email and the rest of the text as the body. The
125- empty line separating summary from body is critical. Tools like
126- rebase can get confused if the empty line is missing.
127-
128- Further paragraphs should be separated with empty lines.
129-
130- - Bullet points are okay, too
131-
132- - Typically a hyphen or asterisk is used for the bullet, preceded
133- by a single space, with blank lines in between, but conventions
134- vary here
135-
136- If you use an issue tracker, put references to them at the bottom,
137- like this:
138-
139- Resolves: #123
140- See also: #456, #789
141-
142- Signed-off-by: Jacky Linker <[email protected] > 121+ ``` text
122+ subsystem: brief, but clear and concise summary of changes
123+
124+ More detailed explanatory text, if necessary. Wrap it to about 72
125+ characters or so. In some contexts, the first line is treated as
126+ the subject of an email and the rest of the text as the body. The
127+ empty line separating summary from body is critical. Tools like
128+ rebase can get confused if the empty line is missing.
129+
130+ Further paragraphs should be separated with empty lines.
131+
132+ - Bullet points are okay, too
133+
134+ - Typically a hyphen or asterisk is used for the bullet, preceded
135+ by a single space, with blank lines in between, but conventions
136+ vary here
137+
138+ If you use an issue tracker, put references to them at the bottom,
139+ like this:
140+
141+ Resolves: #123
142+ See also: #456, #789
143+
144+ Signed-off-by: Jacky Linker <[email protected] > 145+ ```
143146
144147This is an example of how to [ automatically close] [ closing ] an issue
145148when the commit is merged to mainline. Several keywords are available.
146149
150+ :lock_with_ink_pen : Signing Commits with GPG
151+ ---------------------------------------------
152+
153+ To ensure the authenticity and integrity of your contributions, we
154+ ** require** all commits to be signed with GPG. This cryptographically
155+ verifies that commits come from a trusted source.
156+
157+ ### Generating a GPG Key
158+
159+ If you don't already have a GPG key, generate one:
160+
161+ ``` bash
162+ $ gpg --full-generate-key
163+ ```
164+
165+ When prompted, choose:
166+ - Key type: ` RSA and RSA ` (default)
167+ - Key size: ` 4096 ` bits (recommended for security)
168+ - Expiration: ` 0 ` (key does not expire)
169+ - Real name and email: Use the same email as your Git configuration
170+
171+ > [ !NOTE]
172+ > We recommend keys that do not expire for signing commits. Expiration
173+ > creates a "usability time bomb" without providing meaningful security
174+ > benefits for code signing. See [ this article] [ pgpfan ] for details.
175+
176+ ### Configuring Git to Sign Commits
177+
178+ First, find your GPG key ID:
179+
180+ ``` bash
181+ $ gpg --list-secret-keys --keyid-format=long
182+ ```
183+
184+ Look for the line starting with ` sec ` , the key ID is the part after the ` / ` .
185+ For example, in ` sec rsa4096/ABCD1234EFGH5678 ` , the key ID is ` ABCD1234EFGH5678 ` .
186+
187+ Configure Git to use your GPG key:
188+
189+ ``` bash
190+ $ git config --global user.signingkey ABCD1234EFGH5678
191+ $ git config --global commit.gpgsign true
192+ ```
193+
194+ The second command enables automatic signing for all commits. Alternatively,
195+ you can sign individual commits with ` git commit -S ` .
196+
197+ ### Publishing Your Public Key
198+
199+ To allow others to verify your signatures, publish your public key to a
200+ keyserver:
201+
202+ ``` bash
203+ $ gpg --keyserver hkps://keys.openpgp.org --send-keys ABCD1234EFGH5678
204+ ```
205+
206+ > [ !IMPORTANT]
207+ > The keyserver will send a verification email to the address associated
208+ > with your key. You ** must** click the link in that email to confirm
209+ > ownership before your key becomes searchable by email address.
210+
211+ Alternative keyservers you can use:
212+ - ` hkps://keyserver.ubuntu.com `
213+ - ` hkps://pgp.mit.edu `
214+
215+ ### Adding Your GPG Key to GitHub
216+
217+ For GitHub to show your commits as "Verified", you need to add your public
218+ key to your account:
219+
220+ 1 . Export your public key:
221+ ``` bash
222+ $ gpg --armor --export ABCD1234EFGH5678
223+ ```
224+
225+ 2 . Copy the entire output, including the ` -----BEGIN PGP PUBLIC KEY BLOCK----- `
226+ and ` -----END PGP PUBLIC KEY BLOCK----- ` lines.
227+
228+ 3 . Go to [ GitHub Settings → SSH and GPG keys] ( https://github.com/settings/keys )
229+
230+ 4 . Click ** New GPG key** and paste your public key.
231+
232+ Now your signed commits will display a "Verified" badge on GitHub! :white_check_mark :
233+
234+ For more details, see GitHub's [ official documentation on commit signature verification] [ gpg-verify ] .
147235
148236:twisted_rightwards_arrows : Pull Requests
149237-----------------------------------------
150238
151- > _ The git repository is the canonical location for information._
239+ > [ !NOTE]
240+ > _ The git repository is the canonical location for all information._
152241
153242A pull request should preferably address a single issue or change. This
154243may of course include multiple related changes, but what is important to
@@ -167,7 +256,6 @@ Buildroot, consider the pull request message body similar to the cover
167256letter for a series of patches -- it's a summary of changes, and it is
168257lost when the changes are merged to the mainline branch.
169258
170-
171259:balance_scale : Code of Conduct
172260-------------------------------
173261
@@ -184,6 +272,8 @@ other contributions that are not aligned to this Code of Conduct."*
184272[ PEP-8 ] : https://peps.python.org/pep-0008/
185273[ RDD ] : https://tom.preston-werner.com/2010/08/23/readme-driven-development
186274[ cbeams ] : https://cbea.ms/git-commit/#seven-rules
187- [ conduct ] : CODE-OF-CONDUCT.md
188- [ DCO ] : https://developercertificate.org/
189- [ closing ] : https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests
275+ [ conduct ] : CODE-OF-CONDUCT.md
276+ [ DCO ] : https://developercertificate.org/
277+ [ closing ] : https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests
278+ [ gpg-verify ] : https://docs.github.com/en/authentication/managing-commit-signature-verification
279+ [ pgpfan ] : https://articles.59.ca/doku.php?id=pgpfan:expire
0 commit comments