= Tips & Tricks for PMC Chair
:toc: left
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

Congratulations on becoming the Chair of the Lucene PMC! Thank you for accepting the role.

The primary responsibilities of the Chair are:

. <<Grant Karma to New Committers,Grant karma for new committers>>
. <<Grant Karma to new PMC Members,Grant karma for new members of the PMC>>
. Deal with <<Security Issues,security issues>> and reports of vulnerabilities
. Make <<Board Reports,quarterly reports>> to the ASF Board
. Handle <<Miscellaneous Requests,miscellaneous requests>> for Git repos, mailing lists, Jenkins access, etc.

== Tools to Help You
As a member of the PMC, you should have already been granted permission to the necessary systems. As Chair, in some cases you have higher permissions.

The following Apache systems help automate some of the things you need to do:

* Whimsy: https://whimsy.apache.org/. The official project roster is stored in Whimsy. This is where you go to add new committers or PMC members, and grant Jenkins permissions.
* Reporter Tool: https://reporter.apache.org/. A wizard here will help you file the quarterly report.
* Apache Self-Serve: https://selfserve.apache.org/. Several tools to help if you need to create new Jira projects, Confluence spaces, GitHub repos, mailing lists, etc.

== Grant Karma to New Committers

When the PMC votes to make a contributor into a committer, the Chair does not usually have to do anything.

Traditionally we expect the person who recommended the new committer to handle inviting the person to become a committer, ensuring their accounts get set up properly, and announcing the change to the dev@lucene list.

If the person is not yet a committer on any other Apache project, they will need to submit an Individual Contributor License Agreement (ICLA) before their account can be created.

Once their ICLA is on file, the Infra team will set up their account and grant them committer permissions.

If the person already has an ICLA on file, anyone on the PMC can go to the  https://whimsy.apache.org/roster/committee/lucene[Lucene roster in Whimsy] and add the person.

See also http://apache.org/dev/pmc.html#noncommitter for details on the process.

=== Jira and Confluence Permissions

Jira and Confluence use Apache's LDAP system for authentication, so once the new committer has been granted the permissions to make commits, they will have updated permissions in those systems also. They will not automatically have Jenkins or GitHub permissions, however.

=== GitHub Permissions

For a new committer to have permissions to make commits via GitHub and to also create, merge, or close GitHub pull requests via the GitHub interface, they must first link their Apache and GitHub user IDs. They can do this by going to https://id.apache.org and filling in the "Your GitHub Username" field.

After adding their GitHub ID, it can take 3-4 hours for the permissions in GitHub to be updated. The committer will need to make sure they have two-factor authentication (2FA) enabled in GitHub in order for the permissions to be granted.

See also https://reference.apache.org/committer/github.

== Grant Karma to new PMC Members

Once a vote to add a new member of the PMC has passed, the Chair must send the proposed change to the Board by sending an email to board@apache.org with a link to the Vote & Result thread from the archives (https://lists.apache.org/).

The board will not respond. After 72 hours, check that the mail appears in the Board archives by sending mail to `board-index@apache.org`. The response should show the notification to the Board was received.

Once the 72 hours has passed, the Chair can go to the https://whimsy.apache.org/roster/committee/lucene[Lucene roster in Whimsy] and change the person from a Committer to a member of the PMC.

See also: http://www.apache.org/dev/pmc.html#newpmc.

== Security Issues

Apache has a dedicated security team that helps handle reports of vulnerabilities in all Apache software.

The standard process for handling vulnerability reports is defined at https://www.apache.org/security/committers.html#vulnerability-handling.

*All vulnerability reports must be handled with discretion and should not be discussed outside the Apache Security team and the PMC.* The reason for this is to prevent the vulnerability from being exploited before we have a chance to come up with proper mitigation steps and/or bug fixes.

=== How Vulnerabilities are Reported
The mailing list security@lucene.apache.org has been set up to handle vulnerability reports. This list includes the Apache Security team, so they do not need to be cc'd on mails to that list. PMC members are unfortunately not automatically subscribed to this list, they must subscribe themselves.

The Apache Security team should be kept in the loop regarding how we decide to handle any vulnerability report. They are not cc'd on mails to private@lucene.apache.org, so if discussion happens there, security@apache.org should be copied where appropriate.

Vulnerabilities may also be reported via Jira. When this happens, the Security Level field in the issue must be set to "Private", which means it can only be viewed by members of the PMC.

If the vulnerability is reported via email, ensure that security@apache.org has a copy of the report, and also file a Jira issue for discussion about mitigation and fix.

=== Mitigation and Fixes

It's up to the PMC as a whole to provide workarounds and/or fixes for all vulnerability reports. Your job as Chair is to ensure that it's happening in a timely manner and according to the process. There's nothing specific you have to do unless others are not doing it.

== Board Reports

The Chair must submit a quarterly report to the Apache Board of Directors. Our schedule is to file reports in March, June, September, and December of any year.

=== Schedule

Reports are due quarterly. A bot will send a reminder that a report is due before the monthly ASF Board meeting;
the report is due a week before the scheduled meeting.

It's customary to send a draft of the report to the PMC for review prior to sending it to the Board.

=== Template & Wizard

A report template is available from https://reporter.apache.org.

To make creating the report easier, a reporting wizard is available at https://reporter.apache.org/wizard/.

The wizard will provide a blank template with the sections already defined. As you use the wizard to write the report, it will show you data and examples to assist you in completing the report.

Open security issues should be reported to the Board. Since Board reports are generally public, discussion of the issues should be in `<private>` tags so they are removed from the report when the Board makes it public after their monthly meeting. This helps prevent details of vulnerabilities from leaking out before they have been mitigated.

=== Board Feedback

After the Board meeting, they may have feedback on the quarterly report. They may simply make a comment, or they may request something as follow-up. Respond to the feedback as appropriate.

== Miscellaneous Requests

=== Add Jenkins Rights

This will allow the user to configure Jenkins jobs.

Just add the committer to the `hudson-jobadmin` group in Whimsy: https://whimsy.apache.org/roster/group/hudson-jobadmin

=== IP Clearance

Code donations are kept in https://svn.apache.org/repos/asf/incubator/public/trunk/content/ip-clearance. For the process, see https://incubator.apache.org/ip-clearance/.

=== Licenses and Passwords

Private PMC files: https://svn.apache.org/repos/private/pmc/lucene/

=== Changing the Chair
The Lucene PMC traditionally rotates the Chair once a year.

When it's time to change Chairs, think of a member of the PMC to replace you and ask if they will be willing to serve a term as Chair.
If they agree, you can start a VOTE thread in private@lucene.apache.org nominating your successor.

Assuming the vote passes, you can send a resolution to the Board for their approval to change the Chair. Include the vote thread in the resolution.
You do not need to wait until the usual quarterly report is due to change the Chair.

Resolution example/template:

----
A. Change the Apache Lucene Project Chair

    WHEREAS, the Board of Directors heretofore appointed <old Chair>
    (<apache id>) to the office of Vice President, Apache Lucene, and

    WHEREAS, the Board of Directors is in receipt of the resignation
    of Adrien Grand from the office of Vice President, Apache
    Lucene, and

    WHEREAS, the Project Management Committee of the Apache Lucene
    project has chosen by vote to recommend <new Chair> (<apache id>)
    as the successor to the post;

    NOW, THEREFORE, BE IT RESOLVED, that <old Chair> is relieved
    and discharged from the duties and responsibilities of the office
    of Vice President, Apache Lucene, and

    BE IT FURTHER RESOLVED, that <new Chair> be and hereby is
    appointed to the office of Vice President, Apache Lucene, to serve
    in accordance with and subject to the direction of the Board of
    Directors and the Bylaws of the Foundation until death,
    resignation, retirement, removal or disqualification, or until a
    successor is appointed.

    Thread: <link to vote thread>
----

The Board will vote to adopt the resolution in their next meeting.

Thank you for being Chair!