X-Git-Url: http://git.marmaro.de/?a=blobdiff_plain;f=README.md;h=566c54e71166241dd314366d6823113f8380b172;hb=ec691e6d72c4d518ff2c1c9f5d0bda377746a00a;hp=8ce957790d1826dcfd827c6b7f9a9c863a7f833e;hpb=634a3558f418f1ac1da5fc1259d9037b0e47fe07;p=mantis2gitlab
diff --git a/README.md b/README.md
index 8ce9577..566c54e 100755
--- a/README.md
+++ b/README.md
@@ -1,55 +1,220 @@
-# YouTrack2GitLab
-Import YouTrack issues into GitLab.
+# Mantis2GitLab
+
+Script for importing Mantis issues into (a new project in) GitLab. The created GitLab issues will have the same
+issue numbers are the corresponding Mantis issues. Please do not use this script against a GitLab project that
+has GitLab issue.
+
+The script performs the following:
+
+ * Reads configuration file and Mantis SVN export
+ * Fetches GitLab Project and Members
+ * Fetches existing issues from GitLab Project
+ * For each Mantis Issue
+ * If a corresonding GitLab issue exists, its Title, Description, Labels and Closed status are updated
+ * Otherwise
+ * If there is a "gap" in Mantis issue numbers, "Skipped Mantis Issue" GitLab issue(s) are created
+ * A new GitLab issue is created with an appropriate Title, Description, Labels and Closed status
## Install
```
-npm install -g youtrack2gitlab
+npm install -g nonplus/mantis2gitlab
```
## Usage
```
-yt2gl -i -u -g -p -t
+m2gl -i options
```
## Options
```
--i, --input
- CSV file exported from YouTrack (Example: issues.csv)
+ -i, --input CSV file exported from Mantis (Example: issues.csv) [required]
+ -c, --config Configuration file (Example: config.json) [required]
+ -g, --gitlaburl GitLab URL hostname (Example: https://gitlab.com) [required]
+ -p, --project GitLab project name including namespace (Example: mycorp/myproj) [required]
+ -t, --token An admin user's private token (Example: a2r33oczFyQzq53t23Vj) [required]
+ -s, --sudo The username performing the import (Example: bob) [required]
+ -f, --from The first issue # to import (Example: 123)
+```
+
+## Config File
+
+In order to correctly map Mantis attributes you should create a JSON file and specify it with the **-c** switch.
+
+### Users
+
+This section maps Mantis `username` (Reporter, Assigned To, etc.) to a corresponding GitLab user name.
+
+```
+{
+ "users": {
+ "mantisUserName1": {
+ "gl_username": "GitLabUserName1"
+ },
+ "mantisUserName2": {
+ "gl_username": "GitLabUserName2"
+ }
+ }
+}
+```
+
+### Mantis URL (optional)
+
+This setting defines the URL to the old mantis installation. When specified, Mantis cases imported in GitLab
+will contain a back-link to their corresponding Mantis issue.
+
+```
+{
+ "mantisUrl": "https://www.oldserver.com/mantis"
+}
+```
+
+### Category Labels (optional)
+
+This section maps Mantis Categories to corresponding GitLab labels.
+
+```
+{
+ "category_labels": {
+ "Admin UI": "area:Admin",
+ "Voter UI": "area:Voter",
+ "Server": "area:Service"
+ }
+}
+```
+
+### Priority Labels (optional)
+
+This section maps Mantis Priorities to corresponding GitLab labels.
+Note that the numeric priorities are used when exporting from SQL.
+
+```
+{
+ "priority_labels": {
+ "20": "priority:low",
+ "low": "priority:low",
+ "40": "priority:high",
+ "high": "priority:high",
+ "50": "priority:urgent",
+ "urgent": "priority:urgent",
+ "60": "priority:immediate",
+ "immediate": "priority:immediate"
+ }
+}
+```
+
+### Severity Labels (optional)
+
+This section maps Mantis Severities to corresponding GitLab labels.
+Note that the numeric severities are used when exporting from SQL.
--u, --users
- User mapping file (Example: users.json)
+```
+{
+ "severity_labels": {
+ "10": "severity:feature",
+ "feature": "severity:feature",
+ "20": "severity:trivial",
+ "trivial": "severity:trivial",
+ "30": "severity:text",
+ "text": "severity:text",
+ "40": "severity:tweak",
+ "tweak": "severity:tweak",
+ "50": "severity:minor",
+ "minor": "severity:minor",
+ "60": "severity:major",
+ "major": "severity:major",
+ "70": "severity:crash",
+ "crash": "severity:crash",
+ "80": "severity:block",
+ "block": "severity:block"
+ }
+}
+```
--g, --gitlaburl
- GitLab URL hostname (Example: gitlab.example.com)
+### Closed Statuses (optional)
--p, --project
- GitLab project name including namespace (Example: mycorp/myproj)
+This section maps which Mantis Statuses indicate that the issue is closed.
+Note that the numeric severities are used when exporting from SQL.
--t, --token
- An admin user's private token (Example: a2r33oczFyQzq53t23Vj)
```
+{
+ "closed_statuses": {
+ "80": true,
+ "resolved": true,
+ "90": true,
+ "closed": true
+ }
+}
+```
+
+## Exporting From Mantis
+
+The input to this script is a CSV file with the following columns:
+
+ * `Id` - Will create a corresponding GitLab *Issue*
+ * `Summary` - Will create a corresponding GitLab *Title*
+ * `Category` - Will create a corresponding GitLab *Label* from `config.category_labels[Category]`
+ * `Priority` - Will create a corresponding GitLab *Label* from `config.priority_labels[Priority]`
+ * `Severity` - Will create a corresponding GitLab *Label* from `config.severity_labels[Severity]`
+ * `Created` - Will be included in the *Description* header
+ * `Updated` - Will be included in the *Description* header, if different from `Created`
+ * `Reporter` - Will be included in the *Description* header
+ * `Assigned To` - Will be included in the *Description* header
+ * `Description` - Will be included in the *Description*
+ * `Info` - Will be appended the *Description*
+ * `Notes` - Will be split on `"$$$$"` and appended the *Description*
+
+### Exporting from Mantis UI
-## User Mapping File
-In order to correctly map users you should create a JSON file with the following format and specify it with the **-u** switch:
+You can export a summary of the Mantis issues from the _View Issues_ page by clicking on the _Export CSV_ button.
+
+**Note:** This export will only include a subset of the issues and is not the recommended approach.
+
+### Exporting from database
+
+The following SQL query pulls all the supported columns from the Mantis database. Make sure you specify the correct `PROJECT_NAME`:
```
-[
- {
- "yt_username": "USER'S USERNAME IN YOUTRACK",
- "yt_name": "USER'S NAME IN YOUTRACK",
- "gl_username": "USER'S USERNAME IN GITLAB",
- "gl_private_token": "USER'S PRIVATE TOKEN IN GITLAB"
- },
- â¦
-]
+SELECT
+ bug.id as Id,
+ project.name as Project,
+ bug.category as Category,
+ bug.summary as Summary,
+ bug.priority as Priority,
+ bug.severity as Severity,
+ bug.status as Status,
+ bug.date_submitted as Created,
+ bug.last_updated as Updated,
+ reporter.username as Reporter,
+ handler.username as "Assigned To",
+ bug_text.description as Description,
+ bug_text.additional_information as Info,
+ GROUP_CONCAT(
+ CONCAt('*', bugnote.date_submitted, ' - ', note_reporter.username, '*
+
+', bugnote_text.note)
+ ORDER BY bugnote.Id
+ SEPARATOR '$$$$'
+ ) as Notes
+FROM
+ mantis_bug_table as bug
+ JOIN mantis_project_table project ON bug.project_id = project.id
+ JOIN mantis_bug_text_table bug_text ON bug.bug_text_id = bug_text.id
+ JOIN mantis_user_table as reporter ON bug.reporter_id = reporter.id
+ LEFT OUTER JOIN mantis_user_table as handler ON bug.handler_id = handler.id
+ LEFT OUTER JOIN mantis_bugnote_table as bugnote ON bugnote.bug_id = bug.id
+ LEFT OUTER JOIN mantis_bugnote_text_table as bugnote_text ON bugnote.bugnote_text_id = bugnote_text.id
+ LEFT OUTER JOIN mantis_user_table as note_reporter ON bugnote.reporter_id = note_reporter.id
+WHERE
+ project.name = 'PROJECT_NAME'
+GROUP BY bug.id
+ORDER BY bug.id
```
## Notes
- Make sure the input CSV file only includes issues for the project you want to import.
-- Make sure that all users have write access to the specified repository or some issues will fail to import. A safer approach is to set repository's **Visibility Level** to **Public** and revert it when the import process is complete.
- In version 6.4.3, GitLab API does not support setting creation date of issues. So all imported issues will have a creation time of now.
- In version 6.4.3, GitLab API fails to import issues with very long titles.
- In version 6.4.3, GitLab does not allow issues to be deleted. So be careful when importing issues into an active project.
@@ -60,14 +225,15 @@ In order to correctly map users you should create a JSON file with the following
+ Initial release
## Author
-**Soheil Rashidi**
+**Stepan Riha**
-+ http://soheilrashidi.com
-+ http://twitter.com/soheilpro
-+ http://github.com/soheilpro
++ http://github.com/nonplus
## Copyright and License
-Copyright 2014 Soheil Rashidi
+
+Based on https://github.com/soheilpro/youtrack2gitlab
+
+Copyright 2015 Stepan Riha
Licensed under the The MIT License (the "License");
you may not use this work except in compliance with the License.