Various bugfixes and enhancements #5

Closed
wants to merge 28 commits into
from
Commits
Jump to file or symbol
Failed to load files and symbols.
+587 −146
Diff settings

Always

Just for now

View
@@ -1,24 +1,48 @@
h1. Trac to GitHub Issues conversion script
-Imports are now working, including comments
+Imports are now working, including comments, and various optional
+metadata (as labels).
+
+h2. Requirements
+
+simplejson (can be installed with 'pip install simplejson')
h2. Usage
<pre class="console">$ ./trac2issues.py --help
-Usage: trac2issues.py [options]
+Usage: trac2issues.py [options] import|dump
Options:
-h, --help show this help message and exit
-t TRAC, --trac=TRAC Path to the Trac project to export.
+ -a ACCOUNT, --account=ACCOUNT
+ Name of the GitHub Account to import into. (If neither
+ this nor --account is specified, user from your global
+ git config will be used.)
-p PROJECT, --project=PROJECT
Name of the GitHub Project to import into.
-x, --closed Include closed tickets.
+ -y, --type Create a label for the Trac ticket type.
-c, --component Create a label for the Trac component.
- -m, --milestone Create a label for the Trac milestone.
+ -r, --reporter Create a label for the Trac reporter.
-o, --owner Create a label for the Trac owner.
- -r, --reporter Add a comment naming the reporter.
- -u URL, --url=URL The base URL for the trac install (will also link to
- the old ticket in a comment).
+ -n, --resolution Create a label for the Trac ticket resolution.
+ -u URL, --url=URL Base URL for the Trac install (if specified, will
+ create a link to the old ticket in a comment).
+ -g ORGANIZATION, --org=ORGANIZATION
+ Name of GitHub Organization (supercedes --account)
+ -s START, --start=START
+ The trac ticket to start importing at.
+ --authors=FILE File to load user login names from. Each line is space
+ separated like: trac-login github-login
+ --additional-comments
+ Add information about the original author and date as
+ a text header in every comment entry.
+
+
+ We no longer have an option to create a label from Trac milestones,
+ because Github issues now supports milestones natively.
+
</pre>
<pre class="console">
@@ -28,5 +52,39 @@ sudo ./trac2issues.py \
-u http://bugs.davglass.com/projects/davglass
</pre>
+h2. Limitations
+
+Does not convert many Trac wiki syntax features to Markdown; so, issues or
+comments that use much Trac syntax will look wrong. One thing we
+do support is the "{{{ ... }}}" literal text delimeters.
+
+It's rather slow: GitHub limits us to 60 API calls per second, and
+each issue might take several calls (one to create the issue, one per
+comment to add).
+
+This varies depending on which options you enable; more = slower.
+
+The Github API does not allow assigning the owner or reporter. This is
+why we have options for attaching those as labels. It's a kludge, yes.
+
+Note that if your github repository already has some issues, you can't
+possibly preserve correct issue numbers. You might maybe be able to
+create a new fork to another account, import your issues to the fork,
+rename the original repository, and transfer ownership of the
+fork. Maybe. Untested.
+
+
+h2. Advice
+
+It is highly recommended to create a scratch github repository to run
+your imports to, and do trial runs until you're happy, before doing it
+to your real project repository. This is because it may take you
+several tries to decide exactly which options you want, and verify
+that it's going to work
+Since there is NO way to delete an issue from github issues, any
+issues you create on your real repository will be there forever.
+This is especially important if you care about preserving issue
+numbers; in that case you should also use the -x option to include
+closed issues.
Oops, something went wrong.