Proposal: Improving Onboarding Experiences

As we rely on volunteers, we should ensure that any newcomer onboarding experiences are welcoming, informative, easy to read, and correctly reflect how our communities work.  The actual materials we share (or don't share in any obvious way) during onboarding vary quite a lot - partly because the people inviting newcomers are volunteers from different project or Foundation cultures too.

Users are the newcomers here: someone being elected as a committer, PMC member, or the like; Owners are the people managing the [VOTE] process and actually using tool(s) to create the new committer account, or are otherwise people already in communities responsible for any official outreach to the newcomer(s).

Improvement Recommendations

• Include an explanatory publicly-accessible URL in every template email, so it's easier to keep the documentation someone reads when onboarding updated. Stable URLs on websites can be found through searching and can be referred to from other docs; most template emails are hidden away or are part of tooling.
• Include as much context as practical in any onboarding-related email.  For example, for ICLA / new account emails, ensure the PMC and any other data is included in each kind of email (either to the new user or to owner/existing PMC) along with explicit instructions that match any tooling.
• Review all onboarding emails for clarity and readability from the perspective of a newcomer to the ASF.
• Review all docs linked from onboarding emails for clarity and readability, and especially consistency with emails and other tooling.
• Ensure all emails during the ICLA → new committer process are consistent, from the Secretary, a PMC, or any other roles.

Secretary Workbench Tool

The Secretary uses a Whimsy tool to process incoming signed ICLA, CCLA, software grant, and other signed documents.  These tasks are done by the Secretary, although they often occour during a larger process of a PMC electing a new committer (where the PMC also communicates with the newcomer).  The Secretary tool organizes metadata, checks in documents, and automatically emails ACK/NAK to the submitter.  Depending on the action, the Secretary may also email a PMC, root@, or others to take action (like then creating a committer account).  Emails are very simple, and only include generic how-to links.

Workbench templates directory of *.erb

Dear <%= @email.display_names.join(', ') %>,

We received this document but we cannot file it as is.
<%= @missing_items %>
Please fill all required fields and resubmit all pages
to secretary@apache.org
https://www.apache.org/licenses/#submitting
Warm Regards,

<%= @sig %>

Sign ICLA

Newcomers sign ICLAs, either unprompted, requested during a project review of a patch or pull request, or during the committer account creation process.  The Secretary handles ACK/NAK of the ICLA itself, and may request account creation, but not other parts of the process.

User Docs https://www.apache.org/licenses/contributor-agreements.html#submitting  This is just a physical how-to of the format, signatures, where to email; it doesn't explain the bigger process or aspects.

User ACK Email  The Secretary sends a template email (see above) to acknowledge receipt of the signed document; actual template depends if the ICLA was for a specific PMC or if the account has already been created.

New Committer Account

Owner Docs  https://apache.org/dev/pmc.html#newcommitter /dev/pmc guide includes a number of different special cases and considerations related to the PMC's process of adding a new committer.

Owner Tool https://whimsy.apache.org/officers/acreq.cgi Whimsy has a Members/Officers-only helper tool that organizes part of the account creation request process. This tool sends a simple form-like email to root@ and others requesting the account.

User ACK Email  The Secretary sends (see above) an ACK if an ICLA is being submitted during the process, both to the submitter and possibly the PMC.

User ACK Email Infra sends an email to the new user once their account is created.  This includes general information about how to manage their committer account, but not information about the project(s) they might have karma on.  https://svn.apache.org/repos/infra/infrastructure/trunk/tools/new_account_creation/mailer/account-welcome.ezt 

Owner ACK Email Infra sends an email to the PMC requesting a new committer in some cases, letting them know they might need to grant additional karma.  https://svn.apache.org/repos/infra/infrastructure/trunk/tools/new_account_creation/mailer/account-project.ezt

Existing Committer, Added To New Project

Owner Docs https://apache.org/dev/pmc.html#karma. PMC Chairs (officers or Members) can use Whimsy roster tooling to add permissions to existing committer accounts.  Whimsy sents out simple ACK emails to the project that such-and-such user was added/removed.

Owner ACK Email Infra may send notification to the PMC that a new committer was added with karma (? not sure about this process?)

New PMC Member

Owner Docs https://apache.org/dev/pmc.html#newpmc The PMC guide steps through the NOTICE steps and updating the roster, and then as an aside mentions how to actually invite the new PMC member and that "New PMC members are required to read the PMC Branding Responsibilities".

There is no specific ACK or invitation email template, so this varies widely by PMC Chair.

New PMC Chair

See improvement plan - done!

Owner Docs https://apache.org/dev/pmc.html#newchair The guide explains briefly how to use Whimsy to submit the chair change resolution.  It also includes apparently outdated instructions to update the /foundation/ web page listing all VPs.

Owner Tool Whimsy's chair change template, accessible from Add Item to an agenda. 

User ACK Email The Secretary uses Whimsy after a meeting's conclusion to send a brief email to new Chairs cc: board@ welcoming to officer position.  https://github.com/apache/whimsy/blob/master/www/board/agenda/views/actions/todos.json.rb The email includes a link to the useful if wordy actual introduction/requirements of a VP position: https://svn.apache.org/repos/private/foundation/officers/advice-for-new-pmc-chairs.txt

There are also ASF-private onboarding processes for Membership, some Officers, and Directors not covered here.

Other Source URLs About Onboarding