You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@allura.apache.org by br...@apache.org on 2014/06/04 22:57:27 UTC
git commit: [#1687] remove old import docs. Need to write new ones
about Importer framework
Repository: allura
Updated Branches:
refs/heads/master fd00be035 -> ed5f7c562
[#1687] remove old import docs. Need to write new ones about Importer framework
Project: http://git-wip-us.apache.org/repos/asf/allura/repo
Commit: http://git-wip-us.apache.org/repos/asf/allura/commit/ed5f7c56
Tree: http://git-wip-us.apache.org/repos/asf/allura/tree/ed5f7c56
Diff: http://git-wip-us.apache.org/repos/asf/allura/diff/ed5f7c56
Branch: refs/heads/master
Commit: ed5f7c562b0f3824f32083caae9a39f0edce636c
Parents: fd00be0
Author: Dave Brondsema <da...@brondsema.net>
Authored: Wed Jun 4 16:57:20 2014 -0400
Committer: Dave Brondsema <da...@brondsema.net>
Committed: Wed Jun 4 16:57:20 2014 -0400
----------------------------------------------------------------------
Allura/docs/index.rst | 1 -
Allura/docs/migration.rst | 131 -----------------------------------------
2 files changed, 132 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/allura/blob/ed5f7c56/Allura/docs/index.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/index.rst b/Allura/docs/index.rst
index 4560c19..d58b7aa 100644
--- a/Allura/docs/index.rst
+++ b/Allura/docs/index.rst
@@ -37,7 +37,6 @@ Running Allura
installation
administration
scm_host
- migration
Using Allura
=====================================================================
http://git-wip-us.apache.org/repos/asf/allura/blob/ed5f7c56/Allura/docs/migration.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/migration.rst b/Allura/docs/migration.rst
deleted file mode 100644
index f5f9d4b..0000000
--- a/Allura/docs/migration.rst
+++ /dev/null
@@ -1,131 +0,0 @@
-.. 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.
-
-Third-party Data Migration
-==========================
-
-Allura provides means to migrate existing project data hosted in other applications.
-At this time, tracker/ticket import is available. The migration procedure is as follows:
-
-1. Export data from your application into ForgePlucker JSON-based interchanged format
- (http://home.gna.org/forgeplucker/forge-ontology.html).
-2. Prepare a tracker in Allura project for import.
-3. Validate import data.
-4. Request/Generate Import API Ticket.
-5. Perform actual migration.
-
-Subsections below discuss each step in more detail.
-
-Exporting data
---------------
-The aim of migration services in Allura was to support various applications and
-data tools. This is achieved by using intermediate format to represent data which
-were exported from 3rd-party application and will be imported into Allura. This
-formated is based on proposals of ForgePlucker project (http://home.gna.org/forgeplucker/)
-and is relatively simple JSON-based format. Please note that there some differences
-to the format as described in ForgePlucker documents, because ForgePlucker format
-is itself not finalized, and there was need to tweak format based on actual usecases
-with Allura. There is currently no standalone description of format understood
-by Allura, output produced by sample exporter(s) provided should be taken as the
-reference.
-
-At this time, only single-tracker imports are supported.
-
-There is a proof-of-concept Trac exporter provided. It is expected that it will be
-elaborated, and more exporters written on as-needed basis, both by Allura developers
-and community. We will be glad to integrate any useful contributions.
-
-Preparing for import
---------------------
-Allura strives to provide as faithful and lossless import as possible. However,
-to achieve this, some help from user is required. The most important part of it
-is ensuring that users referenced in the import JSON are available in Allura.
-If, during import, some user does not exist, corresponding field in a ticket will
-be set to Nobody/Anonymous.
-
-It oftentimes not possible or plausible to ensure that all submitting users have
-account on the forge, but it is usually more important to make sure that
-assigned-to users do. Assigned-to users are usually a smaller set, like
-members of your project, so it's good idea to ask them to register an account
-before performing import.
-
-Another common issue is that username in original tracker and in the forge do not
-match. The import service provides the ability to specify user mapping to overcome this.
-For example, you can specify that user "john" as appearing in JSON should be
-translated to "john2" in the forge. Mapping should be prepared in the form of JSON
-dictionary, e.g. ``{"john": "john2"}``.
-
-Other issue is extra ticket fields appearing in the original tracker. Allura
-tracker by default support small number of generally usable fields. More fields
-can be created as "custom" ones. Import service has the to automatically create
-custom fields for unknown fields appearing in import JSON. However, it will use
-"string" type for them. If that's not what you want, you should pre-create all
-custom fields in the custom tracker with correct types.
-
-
-Validating import data
-----------------------
-Before you do actual import, it makes sense to perform "dry run" import to
-catch any issues. This is especially true as real import requires special
-permission granted by an "API ticket" (more on this below).
-
-Both validating and actual import is executed using a REST API call. There's
-however a script provided which takes command-line arguments, pre-processes
-them and executes need REST API call. This script is called ``allura_import.py``.
-To run it in the validation mode::
-
- python allura_import.py -u http://sourceforge.net \
- -a <API key> -s <Secret key>
- -p test -t bugs \
- --user-map=users.json \
- --validate import.json
-
-
-Getting Import API ticket
--------------------------
-To perform actual import, you should request an Import API ticket from site
-administrator. For user-facing documentation for SourceForge.net, please refer
-to the corresponding section at https://sourceforge.net/p/forge/documentation/ToC/ .
-
-Below are described site admin's step to generate an API ticket on user's request.
-
-Visit /nf/admin/ link of the site for Site Admin pages. Select "API Tickets" from
-left navigation menu. There will be a form to generate a new ticket and a list of
-existing API tickets (most recently generated first) below it. To create a ticket,
-fill in following information:
-
-* Username - all actions performed using the ticket will be tied to this account.
-* Capabilities (JSON) - all API tickets must have capabilities (represented with
- JSON dictionary) set. For import, this should be ``{"import": [<nbhd_name>, <project_shortname>}``,
- e.g. ``{"import": ["Projects", "test"]}``. For multiple projects, several tickets must be created.
-* Expiration date - All API tickets are time-limited, with default active duration
- of 48 hours, all actions using the ticket must be performed within this timeframe.
-
-Once a ticket is generated (will be shown topmost in the list), API ticket and secret
-key values must be passed securely to the requesting user.
-
-
-Performing actual import
-------------------------
-The same script ``allura_import.py``, is used for actual import, you just should
-omit ``--validation`` option and use API ticket/secret pair::
-
- python allura_import.py -u http://sourceforge.net \
- -a <API ticket> -s <ticket secret>
- -p test -t bugs \
- --user-map=users.json \
- import.json