From d291dad627ee25c4b57eb8e9dd96483057ff4838 Mon Sep 17 00:00:00 2001 From: Andrew Wetmore Date: Tue, 22 Dec 2020 16:25:11 -0400 Subject: [PATCH] Update transitioning_asf.ad Edits for readability. In addition, the original text assumes a migration to a Subversion repository. My colleagues tell me that in the last few years all new podlings have imported their code into Git repositories. It might be a good idea for some wise person to review this page and confirm that it is good guidance for the current reality. --- pages/guides/transitioning_asf.ad | 105 ++++++++++++------------------ 1 file changed, 43 insertions(+), 62 deletions(-) diff --git a/pages/guides/transitioning_asf.ad b/pages/guides/transitioning_asf.ad index 2a61eee97..6e8e4c2b7 100644 --- a/pages/guides/transitioning_asf.ad +++ b/pages/guides/transitioning_asf.ad @@ -18,89 +18,74 @@ Apache Incubator PMC :toc: :imagesdir: ../images/ -For corporate contributions, the SGA or CCLA MUST be completed, submitted -and received before the code is imported. +For corporate contributions, you MUST complete and submit the SGA or CCLA, and Apache must receive it, before you import code. For contributions composed of patches from individual contributors, it is safe to import the code once the major contributors (by volume) have completed ICLAs or SGAs. -In either case, the code to be imported should be attached to a JIRA -and then imported. It is recommended that the previous version -control system is tagged so that the imported version is precisely known. +In either case, attach the code to be imported to a JIRA ticket and then import it. We recommend that you tag the previous version +control system so we know the precise version you are importing. -A public record MUST be made of the code imported. If the import is not -attached to JIRA then it MUST be committed to version control. +You MUST make a public record of the code you import. If you do not attach the import to a JIRA ticket, you MUST committed it to version control. == Importing History -The incoming code can either be committed as a snapshot or as a complete version -control export including history (provided that the import is available in a format -readable by subversion). -Importing with history allows existing open source projects who want to maintain -older versions at Apache to easily perform source diffs and so on. Import just the +You can commit the incoming code as a snapshot or as a complete version +control export, including history (provided that the import is available in a format +readable by Github or Subversion, depending on where the new repository is). +Importing with history allows existing open source projects that want to maintain +older versions at Apache to easily perform source diffs and so on. Importing just the latest code allows a clean break to be made with the past. The choice is left to the community of the incoming project. -The infrastructure team will perform the import including -mapping IDs but it is an operation that requires skill, time and care. In this case, -please ask the infrastructure team politely. - -If you are importing from a github repository, you'll need to add one of our infra staff members as an admin to perform a move. - == Audit Cryptography -Before the code base is committed into an Apache repository, the contribution +Before you commit the code base into an Apache repository, the contribution link:http://www.apache.org/dev/crypto.html[MUST] be checked and any restricted cryptography reported appropriately. Read and follow link:http://www.apache.org/dev/crypto.html[this guide]. == Initial Clean Up -Once a JIRA has been created, the source should be cleaned up. +Once you have created a JIRA ticket, it is time to clean up the source code. -- Ensure source files use the standard Apache boilerplates. This may mean replacing existing license headers. The tools in link:https://svn.apache.org/repos/private/committers/tools[private/committers/tools] and link:https://svn.apache.org/repos/private/committers/relicense[private/committers/relicense] may be useful. +- Ensure source files use the standard Apache boilerplate headers. This may mean replacing existing license headers. The tools in link:https://svn.apache.org/repos/private/committers/tools[private/committers/tools] and link:https://svn.apache.org/repos/private/committers/relicense[private/committers/relicense] may be useful. - Ensure that NOTICE and LICENSE documents are present and correct. Mentors should assist with this. -- Add any required notices. Consider moving copyright attributions from source documents to the NOTICE. Read link:http://www.apache.org/legal/src-headers.html[Apache policy on headers]. -- Audit the source for any potential licensing issues. Any which are found should either resolved immediately (when required) or noted in the status document for later. +- Add any required notices. Consider moving copyright attributions from source documents to the NOTICE file. Read the link:http://www.apache.org/legal/src-headers.html[Apache policy on headers]. +- Audit the source for any potential licensing issues. Resolve any issues you find immediately or note them in the status document for later attention. -It is recommended that the initial clean up be is started -before the code is committed. It MUST be completed before any -releases are cut. +We recommend that you start the initial cleanup before you commit the code. You MUST complete it before creating any +releases. == Clean Up Best Practice -It is recommended that version control is used to create a -public record of the process. This will assist anyone -auditing the code provenance (now or in the future) to -easily perform due diligence without contacting the people -who performed the clean up. The clean up process should +We recommend that you use version control to create a +public record of the cleanup process. This will assist anyone +auditing code provenance (now or in the future) to +easily perform due diligence without having to contact the people +who performed the cleanup. The cleanup process should therefore clearly document (using version control) the evolution of the IP licensing. -Particular care needs to be taken with commit messages -during clean up. The intended audience needs to include +Take particular care with commit messages +during cleanup. The intended audience needs to include lawyers and code auditors. Members of the public need to be able to follow and understand the process from these messages alone. -It is therefore recommended that the initial source is -(after being expanded from the archive) checked in as is -into a special directory (*${project}/trunk/import* is suggested). The original packaging, copyright statements -and license notices should be preserved. A standard Apache -LICENSE and appropriate NOTICE should be added at the top +We therefore recommend that, after you expand the initial source from the archive) you check it into a special directory (we suggest *${project}/trunk/import*) as is. This will preserve the original packaging, copyright statements +and license notices. Add the standard Apache +LICENSE and an appropriate NOTICE at the top for the copyright for the collective work (see link:http://www.apache.org/legal/src-headers.html[policy]). Take particular care with this commit message. As with any patch that contains code which is not the original work -of the committer, the JIRA url (for the artifact imported) -needs to be included together with notes about the original -copyright owner and any associated paperwork. The fact that -this is a exact import including original headers should be -noted to stop any queries about these foreign headers. +of the committer, you need to include the url of the Jira ticket (for the artifact imported), together with notes about the original +copyright owner and any associated paperwork. Note that this is an exact import including original headers, to stop any queries about these foreign headers. The cleanup should then proceed in a number of commits. If -the source provenance is complex, break the process up into -a number of logical steps committing each in turn with a +the source provenance is complex, break the process into +a number of logical steps, committing each in turn with a good message. In particular, take care when relocating copyright @@ -108,17 +93,16 @@ statements and license notices into the NOTICE in the root directory: consider moving each copyright owner individually so that it is easier to audit. (See link:http://www.apache.org/legal/src-headers.html#notice[policy].) -Once a section of code has been cleaned up -(and link:#repackaging[repackaged], if necessary) normal development can begin. +Once you have cleaned up (and link:#repackaging[repackaged], if necessary) a section of code, normal development on it can begin. == On Repackaging -It is recommended - but not mandated - that source is repackaged +We recommend - but do not require - that you repackage source code under the Apache namespace. There is no need to use the incubator -namespace. For example, Java source might be repackaged to +namespace. For example, you might repackage Java source code to *org.apache.foo.Bar* or a DTD to *http://podling.apache.org/foo/bar*. -Existing open source projects moving to Apache may well need to consider +Existing open source projects moving to Apache may need to consider carefully how they will approach this transition. == Update Documents @@ -126,15 +110,14 @@ carefully how they will approach this transition. Check the documentation for references to the old home of the project and update them with references to Apache. -Read -link:http://incubator.apache.org/guides/branding.html[Branding Guide]. -Ensure that appropriate disclaimers are added to the appropriate documentation. +Read the Apache link:http://incubator.apache.org/guides/branding.html[Branding Guide]. +Add appropriate disclaimers to the appropriate documentation. Consider adding a *DISCLAIMER* text document. === Update Build -If the project uses link:http://maven.apache.org[Apache Maven], the pom will -need to be updated to reflect that the project is now at Apache. In particular: +If the project uses link:http://maven.apache.org[Apache Maven], you need to update the pom to reflect that the project is now at Apache. In particular: + - Update *mailingLists* - Update *organization* - Update *url* @@ -142,20 +125,18 @@ need to be updated to reflect that the project is now at Apache. In particular: - Check *licenses* - Update *scm* - Update *groupId* -- Update *manifestEntries*. It is recommended that the -standard Apache settings are used +- Update *manifestEntries*. We recommend that you use the standard Apache settings - Update *developers* to use apache IDs (when known) - Update *distributionManagement* - Consider specifying a link:http://maven.apache.org/pom.html#relocation[relocation] If the project uses link:http://ant.apache.org[Apache Ant], the build script will probably need to be updated. In particular: -- Ensure any MANIFESTs generated refer to Apache. It is recommended that the standard Apache settings are used. +- Ensure any MANIFESTs generated refer to Apache. We recommend that you use the standard Apache settings. - Check that *LICENSE*, *NOTICE* and - if appropriate - *DISCLAIMER* documents are copied into binary artifacts == Issue Tracking Transition -Issues for Apache projects should be tracked on Apache hardware. Some projects arrive -with existing issues tracking. So, in the end these need to be replaced (for new development -at least) by the Apache issues tracker. Options need to be discussed publicly on list -and a consensus reached about the best transition strategy. +We track issues for Apache projects on Apache hardware. Some projects arrive +with existing issue tracking systems. The project needs to move, for new development +at least, to an Apache issue tracker. Discuss options and reach a consensus on the public dev@ email list about the best transition strategy.