一次Mentor创建新项目的流程记录 （IPMC建设新项目指南）

[jixuan1989]

IPMC建设新项目指南.md

本文翻译自https://incubator.apache.org/guides/mentor.html

本文适用于项目已经在 general@incubator.apache.org 投票通过的孵化器项目，后续由Mentor创建各种基础设施的过程。

介绍

在孵化器PMC (IPMC)接受了一个podling（指新项目）后，需要有一个导师设置如下内容:

• 添加podling元数据
• 创建初始podling状态页面，
• 创建或者申请IPMC或基础设施团队的其他人创建polding所需的其他资源(如电子邮件列表，Git或Subversion代码存储库，bug跟踪器，和wiki)。

(译者注：podling相关的svn基地址是：https://svn.apache.org/repos/asf/incubator/public/trunk/)

将Podling加入到podling摘要文件中

在svn的 content/podlings.xml中将podling添加到podling摘要文件中 （可以找找文件里面 status="current" 的项目，将其拷贝当作模板）。

参考格式：

    <podling name="HugeGraph" status="current" resource="hugegraph" sponsor="Incubator" startdate="2022-01-23">
        <description>A large-scale and easy-to-use graph database</description>
        <reporting group="2" monthly="true"> February, March, April </reporting>
        <champion availid="ningjiang">Willem Ning Jiang</champion>
        <mentors>
            <mentor username="lidongdai">Lidong Dai</mentor>
            <mentor username="panjuan">Trista Pan</mentor>
            <mentor username="hxd">Xiangdong Huang</mentor>
            <mentor username="liyu">Yu Li</mentor>
        </mentors>
    </podling>

注意，reporting非常重要，孵化器项目需要每月汇报。同时需要指明初始的三个月是什么（第一个月是进入孵化器的下个月）。

一旦前三个月的报告完成后，就要mentor把monthly属性删除，并且把后面的三个月份列举给删除。
注意第一份报告可能非常短，IPMC可以指导一下。详见PPMC指导

初始化 Podling 状态页面

导师需要创建podling状态页面来跟踪项目。在有PPMC可以更新页面之前，导师需要负责页面更新。

状态页面是孵化器对项目进展的记录。导师或PPMC必须在孵化期间使其保持最新。该页面的一些信息可以从podling提案中获得。随着启动过程的继续和项目创建资源，PPMC应该更新页面。

状态页面模板包含了所需的操作列表，其中那些不合适本项目的，可以删除。

状态页面对孵化工作流很有帮助。志愿者可以使用它来签署各种任务，并跟踪进展。一旦邮件列表建立起来并且有人订阅了，就可以使用dev@列表进行任务讨论。

资源

您需要根据所处理的文件以特定的顺序申请资源。
在对SGAs进行归档之前，不要申请源码仓库资源，例如，源代码尚未获得Apache许可或依赖满足A类许可。

项目的提案中应包括所需资源的清单。Infra团队在得到恰当的申请后会创建一些; IPMC成员(通常是导师)可以创建其他的内容。

Infra有一个指南，叫做Infra和孵化器，帮助您了解资源申请的流程，并指导您申请资源。

您需要创建的第一个资源是LDAP和DNS。通过Apache Infra Jira→创建任务从Infra 申请它们。

一旦这些项目可用，就创建邮件列表。其他资源通常将信息发布到这些列表。

申请邮件列表

Apache电子邮件列表需要志愿者来做审核员。在您设置电子邮件列表之前，至少需要一个志愿者，并且以后还可以添加新的审核员。审核是一个相当简单的任务，尽管版主可能想要设置垃圾邮件过滤。我们建议每个podle至少有三个审核员来分担负载。

提案应该包含请求电子邮件列表所需的其余信息。由于孵化器是负责任的顶级项目，所以域名必须是incubator.apache.org。例如:

• dev@${podling}.incubator.apache.org
• commits@${podling}.incubator.apache.org
• private@${podling}.incubator.apache.org

一般刚开始的时候不需要创建user@，对于用户或者开发者可以都集中到dev@去。此外，进入podling前如果已经有了一些交流渠道，也可以保留下来，不过要在dev@ 列表中讨论和决定此事。

注意，如果你在使用SVN，那么所有在http://svn.apache.org/repos/asf/incubator/${podling} 的提交记录都会被发到commits@ 邮件列表。 如果要修改，则需要IPMC在asf-mailer.conf中增加特殊配制。

Infra团队有一个创建邮件列表的工具，来简化此事。 创建后，会有通知邮件被发到private@incubator列表。

当创建了邮件列表后，要记得更新项目状态页面。

一旦commits邮件列表被创建出来，项目需要审查下svn的/incubator/${podling} 树，因为之前的所有代码提交都没有邮件通知。

邮件归档

在此处 设置公开邮件的归档。导师无需做任何处理。
使用lists.apache.org也可以看归档邮件。

许多项目邮件列表还会使用额外的归档服务（例如 Mail Archive MARC). 这些归档服务有助于项目的曝光。但是这些需要手动来订阅。

你还必须手动创建新闻到邮件列表的订阅桥接，例如 Nabble 。这个也有助于增加曝光，但是要注意 Nabble的新闻用户可能并不知道他们正在向邮件列表发送信息。

邮件列表管理员

Apache 使用 ezmlm。 更多详情需要参见其它教程1, 教程2 。

邮件列表转换

这部分是在说如果过去项目有非apache的邮件列表，该怎么迁移。暂不涉及，不翻译。

自助服务

绝大多数资源都可以通过自助服务来建立，包括设置Git仓库、邮件列表、JIRA、Confluence Wiki。

JRIA

要申请JIRA，从这里申请。

其他issue 跟踪系统

如果要使用其他的issue跟踪系统，请向infra jira发送申请。
记得完成后要通知社区。

Git 迁移

如果要做Git的迁移，则需要写一个 New Git Repository的infra 申请，请求从已有的组织中迁移到apache组织。

Gitbox 申请

要申请一个Gitbox仓库地址的话，要首先写 GitBox Integration 申请。一旦你的podling被加入，你就可以使用如下链接：https://gitbox.apache.org/ 来管理你的Gitbox仓库和用户信息。

Podling 引导

任务列表：

• 确保mentor是IPMC
• 增加podling到汇报列表
• 初始化项目状态页面
• 培训未来的提交者
• 做IP检查
• 签署CLA、CCLA
• 签署SGA
• 申请资源：Email并确保所有的PPMC都订阅了private@
• 申请资源：issue tracking，考虑过去的issue tracking的迁移
• 创建网站

以HugeGraph为例的实际操作

1. svn co https://svn.apache.org/repos/asf/incubator/public/trunk/content

2. 修改content/podlings.xml 添加：

    <podling name="HugeGraph" status="current" resource="hugegraph" sponsor="Incubator" startdate="2022-01-23">
        <description>A large-scale and easy-to-use graph database</description>
        <reporting group="1" monthly="true"> February, March, April </reporting>
        <champion availid="ningjiang">Willem Ning Jiang</champion>
        <mentors>
            <mentor username="lidongdai">Lidong Dai</mentor>
            <mentor username="panjuan">Trista Pan</mentor>
            <mentor username="hxd">Xiangdong Huang</mentor>
            <mentor username="liyu">Yu Li</mentor>
        </mentors>
    </podling>

3. svn commit -m "add HugeGraph project"
4. 申请域名，参考 https://issues.apache.org/jira/browse/INFRA-22815
5. 创建邮件列表：https://selfserve.apache.org/mail.html
6. 在content/projects/ 下新建项目文件 hugegraph.xml，建议找一个已有的孵化项目拷贝过来修改。
   ``

<?xml version="1.0" encoding="UTF-8"?>
<document>
  <properties>
    <title>Apache HugeGraph Project Incubation Status </title>
    <link href="http://purl.org/DC/elements/1.0/" rel="schema.DC"/>
  </properties>
  <body>
    <section id="HugeGraph+Project+Incubation+Status">
      <title>Apache HugeGraph Project Incubation Status</title>
      <p>This page tracks the project status, incubator-wise. For more general
         project status, look on the project website.</p>
    </section>
    <section id="Description">
      <title>Description</title>
      <p>HugeGraph is a high performance scalable graph database.</p>
    </section>
    <section id="News">
      <title>News</title>
      <ul>
        <li>2022-01-23 Project enters incubation.</li>
      </ul>
    </section>
    <section id="Project+info">
      <title>Project info</title>
      <table>
        <tr>
          <th>item</th>
          <th>type</th>
          <th>reference</th>
        </tr>
        <tr>
          <td>Website</td>
          <td>www</td>
          <td id="www">
            <a href="http://HugeGraph.apache.org/">http://hugegraph.apache.org/</a>
          </td>
        </tr>
        <tr>
          <td>Mailing list</td>
          <td>dev</td>
          <td id="mail-dev"><code>dev</code><code>@</code><code>hugegraph.apache.org</code></td>
        </tr>
        <tr>
          <td>.</td>
          <td>private</td>
          <td id="mail-private"><code>private</code><code>@</code><code>hugegraph.apache.org</code></td>
        </tr>
        <tr>
          <td>.</td>
          <td>issues</td>
          <td id="mail-commits"><code>commits</code><code>@</code><code>HugeGraph.apache.org</code></td>
        </tr>
        <tr>
          <td>Bug tracking</td>
          <td>Github Issue</td>
          <td id="tracker">
            <a href="https://github.com/apache/hugegraph/issues">https://github.com/apache/hugegraph/issues</a>
          </td>
        </tr>
        <tr>
          <td>Source code</td>
          <td>incubator-hugegraph</td>
          <td>https://github.com/apache/incubator-hugegraph.git</td>
        </tr>
        <tr>
          <td>.</td>
          <td>incubator-hugegraph-computer</td>
          <td>https://github.com/apache/incubator-hugegraph-computer.git</td>
        </tr>
        <tr>
          <td>.</td>
          <td>incubator-hugegraph-commons</td>
          <td>https://github.com/apache/incubator-hugegraph-commons.git</td>
        </tr>
        <tr>
          <td>.</td>
          <td>incubator-hugegraph-doc</td>
          <td>https://github.com/apache/incubator-hugegraph-doc.git</td>
        </tr>
        <tr>
          <td>.</td>
          <td>incubator-hugegraph-toolchain</td>
          <td>https://github.com/apache/incubator-hugegraph-toolchain.git</td>
        </tr>
        <tr>
          <td>.</td>
          <td>incubator-hugegraph-site</td>
          <td>https://github.com/apache/incubator-hugegraph-site.git</td>
        </tr>
        <tr>
          <td>Roster</td>
          <td>people.apache</td>
          <td><a href='http://people.apache.org/phonebook.html?podling=hugegraph'>HugeGraph Roster</a></td>
        </tr>
        <tr>
          <td>Roster Login</td>
          <td>people.apache</td>
          <td><a href='https://whimsy.apache.org/roster/ppmc/hugegraph'>HugeGraph Roster Login</a></td>
        </tr>
        <tr>
          <td>Champion</td>
          <td>ningjiang</td>
          <td>Willem Ning Jiang</td>
        </tr>
        <tr>
          <td>Mentors</td>
          <td>lidongdai</td>
          <td>Lidong Dai</td>
        </tr>
        <tr>
          <td>.</td>
          <td>panjuan</td>
          <td>Juan Pan</td>
        </tr>
        <tr>
          <td>.</td>
          <td>hxd</td>
          <td>Xiangdong Huang</td>
        </tr>
        <tr>
          <td>.</td>
          <td>liyu</td>
          <td>Yu Li</td>
        </tr>
        <tr>
          <td>Committers</td>
          <td> </td>
          <td></td>
        </tr>
        <tr>
          <td>.</td>
          <td></td>
          <td> </td>
        </tr>
      </table>
    </section>
    <section id="Incubation+status+reports">
      <title>Incubation status reports</title>
      <ul>
        <li><a href='https://whimsy.apache.org/board/minutes/hugegraph.html'>HugeGraph Board Reports</a></li>
      </ul>
    </section>
    <section id="Incubation+work+items">
      <title>Incubation work items</title>
      <section id="Project+Setup">
        <title>Project Setup</title>
        <p>This is the first phase on incubation, needed to start the project at Apache.</p>
        <p>
          <em>Item assignment is shown by the Apache id.</em>
          <em>Completed tasks are shown by the completion date (YYYY-MM-dd).</em>
        </p>
        <section id="Identify+the+project+to+be+incubated">
          <title>Identify the project to be incubated</title>
          <table>
            <tr>
              <th>date</th>
              <th>item</th>
            </tr>
            <tr>
              <td>2022-01-23</td>
              <td>Make sure that the requested project name does not already exist. <a href="http://www.apache.org/foundation/marks/naming.html">Please follow
                the guide to ensure a suitable project/product name.</a></td>
            </tr>
            <tr>
              <td>N/A</td>
              <td>If request from an existing Apache project to adopt an external
                  package, then ask the Apache project for the SVN module and mail
                  address names.</td>
            </tr>
            <tr>
              <td>N/A</td>
              <td>If request from outside Apache to enter an existing Apache project,
                  then post a message to that project for them to decide on acceptance.</td>
            </tr>
            <tr>
              <td>N/A</td>
              <td>If request from anywhere to become a stand-alone PMC, then assess the
                  fit with the ASF, and create the lists and modules under the
                  incubator address/module names if accepted.</td>
            </tr>
          </table>
        </section>
        <section id="Infrastructure">
          <title>Infrastructure</title>
          <table>
            <tr>
              <th>date</th>
              <th>item</th>
            </tr>
            <tr>
              <td>2022-01-29</td>
              <td>Request DNS (first step after creating podling status page)</td>
            </tr>
            <tr>
              <td>2022-01-29</td>
              <td>Request Mailing Lists</td>
            </tr>
            <tr>
              <td>2022-04-18</td>
              <td>Request git repositories</td>
            </tr>
            <tr>
              <td>2022-04-18</td>
              <td>Ask infrastructure to set up issue tracker (Github Issue)</td>
            </tr>
            <tr>
              <td>2022-04-18</td>
              <td>Ask infrastructure to set up wiki (<a href='https://cwiki.apache.org/confluence/display/HUGEGRAPH'>Confluence</a>)</td>
            </tr>
            <tr>
              <td>2022-04-18</td>
              <td>Migrate the project to our infrastructure. Completed</td>
            </tr>
          </table>
        </section>
        <section id="Interim+responsibility">
          <title>Mentor-related responsibility/oversight</title>
          <table>
            <tr>
              <th>date</th>
              <th>item</th>
            </tr>
            <tr>
              <td>-</td>
              <td>Subscribe all Mentors on the pmc and general lists.</td>
            </tr>
            <tr>
              <td>2022-04-18</td>
              <td>Give all Mentors access to the incubator Git repository.
                (to be done by the Incubator PMC chair or an Incubator PMC
                Member wih karma for the authorizations file)</td>
            </tr>
            <tr>
              <td>2022-04-18</td>
              <td>Tell Mentors to track progress in the file
                  'incubator/projects/HugeGraph.html'</td>
            </tr>
          </table>
        </section>
        <section id="Copyright">
          <title>Copyright</title>
          <table>
            <tr>
              <th>date</th>
              <th>item</th>
            </tr>
            <tr>
              <td>-</td>
              <td>Check and make sure that the papers that transfer rights to the ASF
                  been received. It is only necessary to transfer rights for the
                  package, the core code, and any new code produced by the project.
              </td>
            </tr>
            <tr>
              <td>-</td>
              <td>Check and make sure that the files that have been donated have been
                  updated to reflect the new ASF copyright.</td>
            </tr>
          </table>
        </section>
        <section id="Verify+distribution+rights">
          <title>Verify distribution rights</title>
          <table>
            <tr>
              <th>date</th>
              <th>item</th>
            </tr>
            <tr>
              <td>-</td>
              <td>Check and make sure that for all code included with the distribution
                  that is not under the Apache license, we have the right to combine
                  with Apache-licensed code and redistribute.
               </td>
            </tr>
            <tr>
              <td>-</td>
              <td>Check and make sure that all source code distributed by the project
                  is covered by one or more of the following approved licenses: Apache,
                  BSD, Artistic, MIT/X, MIT/W3C, MPL 1.1, or something with essentially
                  the same terms.</td>
            </tr>
          </table>
        </section>
        <section id="Establish+a+list+of+active+committers">
          <title>Establish a list of active committers</title>
          <table>
            <tr>
              <th>date</th>
              <th>item</th>
            </tr>
            <tr>
              <td>-</td>
              <td>Check that all active committers have submitted a contributors
                  agreement.</td>
            </tr>
            <tr>
              <td>-</td>
              <td>Add all active committers in the relevant section above.</td>
            </tr>
            <tr>
              <td>-</td>
              <td>Ask root for the creation of committers' accounts in
                  LDAP.</td>
            </tr>
          </table>
        </section>
        <section id="Project+specific">
          <title>Project specific</title>
          <p>
            <em>Add project specific tasks here.</em>
          </p>
        </section>
      </section>
      <section id="Incubation">
        <title>Incubation</title>
        <p>These action items have to be checked for during the whole incubation process.</p>
        <p>
          <em>These items are not to be signed as done during incubation, as they
              may change during incubation.</em>
          <em>They are to be looked into and described in the status reports and
              completed in the request for incubation signoff.</em>
        </p>
        <section id="Collaborative+Development">
          <title>Collaborative Development</title>
          <ul>
            <li>Have all of the active long-term volunteers been identified and
                acknowledged as committers on the project?
            </li>
            <li>Are there three or more independent committers? (The legal definition
                of independent is long and boring, but basically it means that there
                is no binding relationship between the individuals, such as a shared
                employer, that is capable of overriding their free will as
                individuals, directly or indirectly.)</li>
            <li>Are project decisions being made in public by the committers?</li>
            <li>Are the decision-making guidelines published and agreed to by all of
                the committers?</li>
          </ul>
        </section>
        <section id="Licensing+awareness">
          <title>Licensing awareness</title>
          <ul>
            <li>Are all licensing, trademark, credit issues being taken care of and
                acknowleged by all committers?</li>
          </ul>
        </section>
        <section id="Project+Specific">
          <title>Project Specific</title>
          <p>
            <em>Add project specific tasks here.</em>
          </p>
        </section>
      </section>
      <section id="Exit">
        <title>Exit</title>
        <p>
          <em>Things to check for before voting the project out.</em>
        </p>
        <section id="Organizational+acceptance+of+responsibility+for+the+project">
          <title>Organizational acceptance of responsibility for the project</title>
          <ul>
            <li>If graduating to an existing PMC, has the PMC voted to accept it?</li>
            <li>If graduating to a new PMC, has the board voted to accept it?</li>
          </ul>
        </section>
        <section id="Incubator+sign-off">
          <title>Incubator sign-off</title>
          <ul>
            <li>Has the Incubator decided that the project has accomplished all of
                the above tasks?</li>
          </ul>
        </section>
      </section>
    </section>
  </body>
</document>

8. 提交， svn add hugegraph.xml, svn commit -m "init hugegraph project status page".
9. 等待CLA、SGA签署 （模板： https://www.apache.org/licenses/contributor-agreements.html ）
10. 发送邮件做代码迁移，示例：

Subject: HugeGraph incubator project request for the GitHub repositories moving service

Content: 

Hi, Infra Team.  
  
HugeGraph's proposal into the Incubator has been voted on and accepted.  
and the SGA is done recently (that is why we start the repositories migration so late).  
  
Please let me know to add whom into hugegraph GitHub organization as the admin, then he/she can do the migration from hugegraph to Apache GitHub.  
  
There are five Github repos in total. And, we hope to move the 4th (hugegraph-doc) to hugegraph-website (for the project's website and documents) :  
  
[1] hugegraph: [https://github.com/hugegraph/hugegraph.git](https://github.com/hugegraph/hugegraph.git "Follow link")  
[2] hugegraph-computer: [https://github.com/hugegraph/hugegraph-computer.git](https://github.com/hugegraph/hugegraph-computer.git "Follow link")  
[3] hugegraph-commons: [https://github.com/hugegraph/hugegraph-commons.git](https://github.com/hugegraph/hugegraph-commons.git "Follow link")  
[4] hugegraph-doc: [https://github.com/hugegraph/hugegraph-doc.git](https://github.com/hugegraph/hugegraph-doc.git "Follow link")  
[5] hugegraph-toolchain:  
[https://github.com/hugegraph/hugegraph-toolchain.git](https://github.com/hugegraph/hugegraph-toolchain.git "Follow link")  
  
[6] vote thread: [https://lists.apache.org/thread/j7glr7dryhszq42v2qwymd85jb28gmnr](https://lists.apache.org/thread/j7glr7dryhszq42v2qwymd85jb28gmnr "Follow link")  
[7] SGA thread: [https://lists.apache.org/thread/3p0xf72swyk5g11z9l1k2138q938yz5p](https://lists.apache.org/thread/3p0xf72swyk5g11z9l1k2138q938yz5p "Follow link")  
  
Many thanks.

10. 在仓库有了之后，需要在website的仓库目录下创建 .asf.yaml文件，写上：

#
# 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.
#
publish:  
 whoami: asf-site

更多.asf.yaml的功能可以参考 https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+features

11. 设置 wiki仓库地址，用如下工具：https://selfserve.apache.org/confluence.html
12. 按照 项目状态页面上列举的事情逐一完成 https://incubator.apache.org/projects/hugegraph.html

[tristaZero]

Cool, much clear. 👍🏻

[imbajin]

关于 github 迁移仓库前的一些 CI/Workflow 补充, 核心是需要将原有 repository settings 中的各种配置仔细确认一遍:

• 需提前检查 settings 的相关 LOGO, Tag, Intro 等信息是否设置正确, 后续默认无设置权限
• 如果原本在 organization 级别设置了共享的 token/secret, 请务必将其转换为仓库级别, 否则迁移后 org 级别属性会全部失效
• 请检查 github actions 的使用符合 Apache Workflow 规范, 否则迁移后无法运行 (优先使用 Github/Apache 官方的 action)
• 请确认 github action/app 中的 required 权限, 以及是否允许强合 PR 等关键权限, 以免后续缺乏合并权限
• 同上, 请确认是否开启了严格的分支保护权限, 这部分后序都需要人工申请修改/去除, 应尽量避免麻烦
• 如需要重命名仓库, 建议提前修改

下面是 Apache Github Actions 限定的细节参考, 更多信息可参考官方 WiKi/JIRA

Actions in this workflow must be: within a repository owned by apache, created by GitHub, verified in the GitHub Marketplace, or matching the following:
/@[a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9]+, AdoptOpenJDK/install-jdk@, JamesIves/github-pages-deploy-action@5dc1d5a, TobKed/label-when-approved-action@, actions-cool/issues-helper@, actions-rs/, al-cheb/configure-pagefile-action@, amannn/action-semantic-pull-request@, apache/, burrunan/gradle-cache-action@, bytedeco/javacpp-presets/.github/actions/, chromaui/action@, codecov/codecov-action@, conda-incubator/setup-miniconda@, container-tools/kind-action@, container-tools/microshift-action@, dawidd6/action-download-artifact@, delaguardo/setup-graalvm@, docker://jekyll/jekyll:, docker://pandoc/core:2.9, eps1lon/actions-label-merge-conflict@, gaurav-nelson/github-action-ma...

[WillemJiang]

添加了一个wiki https://github.com/alc-beijing/alc-site/wiki/IPMC%E5%BB%BA%E8%AE%BE%E6%96%B0%E9%A1%B9%E7%9B%AE%E6%8C%87%E5%8D%97
承载这部分内容。