This is the documentation for Self-serve committer managament via your repositories INFO.yaml file. The purpose of the INFO file is two fold, the project committers can use it to act as administrators of their project, and it provides a clear record of who the committers and project lead are, and who autorized their committer permissions.
Adding someone as a committer requires a change-set against your projects INFO.yaml The change should add the needed information, including an approval link if your project requires it. Upon a successful merge automation will process the change and update permissions as needed.
Some projects TCS’s require approval to add committers and/or PTL. If this is the case, append a link to the meeting minutes in the tsc: changes: section
Filling out the INFO file¶
The identity site will provide you with the values for your user.
name: '' email: '' company: '' id: ''
Filling out the REPOSITORIES section¶
In this section you will list your repository, one (1) repository which this INFO file handles. Each repository must have its own INFO file.
repositories: - example
Do not have more than one repository under the repositories heading. Below is an example of what not to do
repositories: - example - example2 - example3
Filling out the TSC approval section¶
In this section you list the history of PTL/Committers. Add each committers entry or exit from the committer list, and one committer per type. Even if not required by your project, a good habit is to provide a link to the Minutes of Meeting with the approval, or if an approval is not needed, to a mail which informs of the decision.
The type can be Approval, Addition or Removal.
tsc: # yamllint disable rule:line-length approval: 'missing' changes: - type: 'approval' name: 'name of new committer' link: 'link to relevant Minutes of Meeting'
Do not forget to add the yammllint option. Otherwise you will get a yamllint error
error line too long (124 > 80 characters) (line-length)
One name per change type. Yamllint will return error otherwise. If you have more names, you need to add each name within its own type section.:
changes: - type: 'Addition' name: 'Person1' link: 'https://wiki.example.org/pages/URL-2-PermissionMail1' - type: 'Addition' name: 'Person2' link: 'https://wiki.example.org/pages/URL-2-PermissionMail2'
For instance, the below faulty change section will give yamllint error:
changes: - type: 'Addition' name: 'Person1' name: 'Person2' link: 'https://wiki.example.org/pages/URL-2-PermissionMail'
error duplication of key “name” in mapping (key-duplicates)
tsc: # yamllint disable rule:line-length approval: 'https://lists.example.org/pipermail/example-tsc' changes: - type: 'addition' name: 'John Doe' link: 'https://wiki.example.org/display/TOC/2019+09+18' - type: 'addition' name: 'Jane Doe' link: 'https://lists.example.org/g/example-TSC/message/3725' - type: 'removal' name: 'Gone Doe' link: 'https://lists.example.org/g/example-TSC/message/3726'
Lint check before submitting¶
Always a good habit to perform a lint check before submitting. One tool for this is the yamllint
sudo dnf install yamllint
And then to check your INFO file
No output indicates no fault found.
To showcase how yamllint will present possible errors, see below example.
Here is an INFO file with more than one name row under the type (one name row allowed).
- type: 'Removal' name: 'Person 1' name: 'Person 2' link: 'https://lists.example.org/g/message/msgnbr'
And this is the result when you do the lint check
yamllint INFO.yaml 98:11 error duplication of key "name" in mapping (key-duplicates) 99:11 error duplication of key "name" in mapping (key-duplicates)
Verify against INFO.yaml schema¶
Also good habit to verify that your INFO.yaml file is following the proper schema.
Download info-schema.yaml and yaml-verify-schema.py
wget -q https://raw.githubusercontent.com/lfit/releng-global-jjb/master/schema/info-schema.yaml \ https://raw.githubusercontent.com/lfit/releng-global-jjb/master/yaml-verify-schema.py
Verify INFO.yaml uses correct schema
python yaml-verify-schema.py \ -s info-schema.yaml \ -y INFO.yaml
No output indicates INFO.yaml file is valid against the schema. Otherwise, ensure you correct any issues before continuing.
Example INFO file¶
--- project: 'example' project_creation_date: '2019-11-13' project_category: '' lifecycle_state: 'Incubation' project_lead: &example_example_ptl name: '' email: '' id: '' company: '' timezone: '' primary_contact: *example_example_ptl issue_tracking: type: 'jira' url: 'https://jira.example.org/projects/' key: 'example' mailing_list: type: 'groups.io' url: 'firstname.lastname@example.org' tag: '' realtime_discussion: type: 'irc' server: 'freenode.net' channel: '#example' meetings: - type: 'gotomeeting+irc' agenda: 'https://wiki.example.org/display/' url: '' server: 'freenode.net' channel: '#example' repeats: '' time: '' repositories: - example committers: - <<: *example_example_ptl - name: '' email: '' company: '' id: '' tsc: # yamllint disable rule:line-length approval: 'missing' changes: - type: '' name: '' link: ''