Re: [Sat] Contributing to drafts is now easier - Core and Crash Recovery

[Rafael Belchior <[e-mail]>]

Hello folks,

Some people tried to contribute to the drafts hosted on our Github but 
found some problems. In order for us to be sure that the draft compiles, 
we shall only accept PRs where the CI passes (a good practice in 
open-source). The CI process defined by internet-draft-template [7] 
checks for syntactic and semantic errors prior to merging the PR.

While this is useful to promote correctness, it is relatively easy for 
the CI to fail due to errors thrown when any problem occurs (notably 
silly syntactic errors such as extra whitespaces, newlines, etc.). These 
prevent the compilation of the editor's draft.

To address this issue,  we have an EditorConfig file in each repo 
(please learn about it here: https://editorconfig.org/). When 
configured, you need to save your draft after your draft editing changes 
(e.g., in VisualCode or another IDE). EditorConfig automatically fixes 
the structural problems (note that the CI can still fail for other 
reasons).

However, note that EditorConfig also acts upon the yaml definition at 
the beginning of the draft, so unfortunately, you need to fix its 
spacing after making any corrections (see attachments). You should make 
sure the yaml looks like "before save", otherwise the CI will fail. If 
someone knows how to fix this problem, please let me know.

I hope it helps you.

Rafael

A 2024-03-22 14:14, Rafael Belchior escreveu:

> Hello All,
> 
> I synced with Rama and thought it would be good to update you on the 
> governance process to update the drafts (specifically core and crash 
> recovery, which use the automation process to manage drafts on Github 
> introduced by Yaron).
> 
> All the authors of each draft with this scheme (core and crash 
> recovery) have admin permissions. We enforce PRs (at least one approval 
> has been given for the PR to be accepted). PRs that do not pass the CI 
> are not accepted. This ensures that:
> 
> 1) The editor's copy update is decentralized (everyone can contribute 
> with reviews/notes directly on the markdown and using Github's PR 
> review feature).
> 
> 2) We ensure that the markdown drafts are valid, i.e., they compile.
> 
> We will always try our best to follow these good practices, but 
> sometimes, circumventing the PR process (e.g., for a hotfix) may be 
> necessary.
> 
> Cheers,
> 
> Rafael
> 
> A 2024-01-23 13:29, VENKATRAMAN RAMAKRISHNA escreveu:
> 
>> Hi Rafael,
>> 
>> I'm catching up on this after a very long time.
>> 
>> These repositories look great, but is there a straightforward way for 
>> me to convert a text file (either as a .txt or txt from a Word doc) to 
>> markdown format so I can create a similar build structure around it? 
>> Or do I need to manually create it?
>> 
>> IETF Datatracker allows submissions in different formats, one of which 
>> is a plaintext file. That's the format I've been using thus far for 
>> the SATP Use Cases draft (and the views drafts too).
>> 
>> Rama
>> 
>> From: sat <[e-mail]> On Behalf Of Rafael Belchior
>> Sent: Thursday, October 26, 2023 12:15 AM
>> To: [e-mail]
>> Subject: [EXTERNAL] [Sat] Contributing to drafts is now easier - Core 
>> and Crash Recovery
>> 
>> Hello Folks, I have been refactoring our SATP-Core repository to 
>> follow IETF recommendations and guidelines for managing drafts in 
>> Github (following i-d-template). Thanks Yaron for the help. Our build 
>> and submission processes are now automated. 
>> 
>> ZjQcmQRYFpfptBannerStart
>> 
>> This Message Is From an External Sender
>> 
>> This message came from outside your organization.
>> 
>> Report Suspicious   [1]  ‌
>> 
>> ZjQcmQRYFpfptBannerEnd
>> 
>> Hello Folks,
>> 
>> I have been refactoring our SATP-Core repository to follow IETF 
>> recommendations and guidelines for managing drafts in Github 
>> (following i-d-template [2]). Thanks Yaron for the help.
>> 
>> Our build and submission processes are now automated. You can access 
>> the latest version of the core draft (Editor's Copy) and respective 
>> diff against the latest published draft (Datatracker). See more here 
>> in the SATP core repo [3].
>> 
>> Contributing to the Core draft is much easier, since the draft is now 
>> in markdown format. One can now fork the repo, make changes to the 
>> draft, and submit a PR. The branch from the PR will get compiled, 
>> making the assessment of changes seamless. You can check detailed 
>> instructions to contribute here [4].
>> 
>> I encourage the authors of the other drafts to setup up their 
>> repositories [5] with this method. Please let me know if you have any 
>> questions or need assistance.
>> 
>> P.S., the latest version of the crash recovery draft is available here 
>> [6].
>> 
>> Cheers,
>> --
>> -- Rafael Belchior
>> 
>> Ph.D. student in Computer Science and Engineering, Blockchain - 
>> Técnico
>> Lisboa
>> https://rafaelapb.github.io/
>> https://www.linkedin.com/in/rafaelpbelchior/-
> 
> --
> -- Rafael Belchior
> 
> Ph.D. student in Computer Science and Engineering, Blockchain - Técnico 
> Lisboa
> https://rafaelapb.github.io/
> https://www.linkedin.com/in/rafaelpbelchior/

-- 
-- Rafael Belchior

Ph.D. student in Computer Science and Engineering, Blockchain - Técnico 
Lisboa
https://rafaelapb.github.io/
https://www.linkedin.com/in/rafaelpbelchior/

Links:
------
[1] 
https://us-phishalarm-ewt.proofpoint.com/EWT/v1/PjiDSg!2U-hiJRVKlMa2u_bWCEPD5UxckTFAtTKhT_I8Y-S2IKKg14YsjRymP6kCfM7BIyi-8cy_8-LfCFGKJNrz7Gj8PQ4UGDjhruqJiJdizQ$
[2] https://github.com/martinthomson/i-d-template
[3] https://github.com/ietf-satp/draft-ietf-satp-core
[4] 
https://github.com/ietf-satp/draft-ietf-satp-core/blob/main/CONTRIBUTING.md
[5] https://github.com/orgs/ietf-satp/repositories
[6] https://github.com/ietf-satp/draft-belchior-satp-gateway-recovery
[7] https://github.com/martinthomson/internet-draft-template