Expanding security assessment facilitator role definition.

[IAXES]

• Various edits to appease the mdl linter.
• Enforcing some style changes (i.e. common indentation and
  trailing period literals in unordered lists, etc.).
• Using a shell script to auto-generate/align the table of contents
  rendered at the top of the document.

[IAXES]

This was the minimum I could get the linter down to. We'd need a prescribed/pre-created mdl linter config file (i.e. that we pull and use locally) if we need 100% of the linter warnings/errors to go away.

governance/roles.md:11: MD007 Unordered list indentation
governance/roles.md:82: MD007 Unordered list indentation
governance/roles.md:248: MD013 Line length
governance/roles.md:251: MD013 Line length

Edit: all good now. Also, found the linter configuration.

[IAXES]

Amended most recent commit to include signature.

[ashutosh-narkar]

@IAXES this looks good. Left a few comments.

[IAXES]

Updated as per feedback.

[ultrasaurus]

I think it is very important not to repeat information that exists elsewhere, but rather link it. For example: soft/hard conflicts are presented here: https://github.com/cncf/tag-security/blob/main/assessments/guide/security-reviewer.md (I think that's a good place for them, though would be open to moving rather than copying if the community feels strongly that this information belongs in governance. If so, consider a small, specific "conflict of interest" doc that can be linked to from both places.)

[ultrasaurus]

Note: this is very hard to review because of all the formatting changes included with (maybe?) substantive changes. Please make clear in the description what expansion of the role you are including, whether this is a proposed change in actual practice or an expanded narrative of what was originally written. This is critical for anything in /governance.

[IAXES]

Note: this is very hard to review because of all the formatting changes included with (maybe?) substantive changes. Please make clear in the description what expansion of the role you are including, whether this is a proposed change in actual practice or an expanded narrative of what was originally written. This is critical for anything in /governance.

I'll do a 2-pass approach in the future (i.e. linter + cosmetic changes first round; substantive/major changes in a follow-up). The change is centered around the "Security review facilitator" / "Security Assessment Facilitator" section. The other changes through the document were just style updates and refactoring the table-of-contents at the top.

[IAXES]

I think it is very important not to repeat information that exists elsewhere, but rather link it. For example: soft/hard conflicts are presented here: https://github.com/cncf/tag-security/blob/main/assessments/guide/security-reviewer.md (I think that's a good place for them, though would be open to moving rather than copying if the community feels strongly that this information belongs in governance. If so, consider a small, specific "conflict of interest" doc that can be linked to from both places.)

The existing location (i.e. security-reviewer) seems fine, IMHO. I just wanted to have a concrete quote/reference (in this case, copy) of it in the current document. If this was a rST/Sphinx doc, for example, I would've just put the example in a separate file and referenced it in both the governance and security-reviewer docs (i.e. made a macro out of the quote). No objections on my end if we should pull it from the governance doc to de-dupe content. :)

[lumjjb]

Thanks for putting this together @IAXES , couple requests for changes!

[lumjjb]

Hi @IAXES just checking in if you've had some time to take a look at the comments!

[IAXES]

Hi @IAXES just checking in if you've had some time to take a look at the comments!

Yep: reviewing now. :)

[netlify]

✅ Deploy Preview for tag-security ready!

Name	Link
🔨 Latest commit	153e5ae
🔍 Latest deploy log	https://app.netlify.com/sites/tag-security/deploys/6553b9e6976bcf0008ae58fc
😎 Deploy Preview	https://deploy-preview-815--tag-security.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[lumjjb]

just a minor nit on practicality of permission assignment in github, else LGTM

[lumjjb]

is this technically possible? I don't believe you can do this in github today? Someone can clarify? @PushkarJ had a bunch of cool github gizmos he implemented through the bot though, so maybe that's possible?

[anvega]

It's possible. This was a hindrance when I was the assessed rather than the assessor. We can accomplish so today by declaring ownership of directories or files in CODEOWNERS: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners#example-of-a-codeowners-file

[achetal01]

I m good with the changes...Thank You IAXES for all the hard work in updating the document.

[anvega]

Nudge @sublimino

[JustinCappos]

This looks fine to me.

[sublimino]

One typo fix suggested, then LGTM too

[mnm678]

LGTM

[stale]

This issue has been automatically marked as inactive because it has not had recent activity.