GitHub - arbox/org-sync: Issue Tracking Synchronization for Emacs Org-mode.
source link: https://github.com/arbox/org-sync
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
README.md
Org-sync: Synchronize Org-mode Files with Bug Tracking systems
CAUTION This package is under a heavy reconstration, please be patient. Feel free to contribute!
Org-sync is a tool to synchronize online bugtrackers with org documents. It is made for relatively small/medium projects: I find Org documents are not really suited for handling large bug lists.
Org-sync
was developed during the Google Summer of Code 2012, the original project
page can be found on Worg:
http://orgmode.org/worg/org-contrib/gsoc2012/student-projects/org-sync/.
Installation
The ordinal way to install Org-sync
is to issue the command:
M-x package-install RET org-sync RET
You could use the bleeding edge version from the repository:
git clone https://github.com/arbox/org-sync.git
Put the org-sync
directory in your load-path and load the org-sync
backend you
need. You can add this to your .emacs
:
(add-to-list 'load-path "path/to/org-sync") (mapc 'load '("org-sync" "org-sync-bb" "org-sync-github" "org-sync-redmine"))
Tutorial
After you have installed org-sync
you need to import a working project.
First open a new org-mode buffer and run M-x org-sync-import
. It prompts you
for an URL. You can try my Github test repo: github.com/arbox/org-sync-test
.
Org-sync should import the issues from the repo.
Note: This is just a test repo, do not use it to report actual bugs.
Now, let's try to add a new issue. First you have to set a user/password to be able to modify the issue remotely.
Set the variable org-sync-github-auth to like so:
(setq org-sync-github-auth '("ostesting" . "thisisostesting42"))
Try to add another issue e.g. insert ** OPEN my test issue
. You can
type a description under it if you want.
The next step is simple, just run M-x org-sync
. It synchronizes all
the buglists in the document.
How to write a new backend
Writing a new backend is easy. If something is not clear, try to read
the header in org-sync.el
or one of the existing backend.
;; backend symbol/name: demo ;; the symbol is used to find and call your backend functions (for now) ;; what kind of urls does you backend handle? ;; add it to org-sync-backend-alist in org-sync.el: (defvar org-sync-backend-alist '(("github.com/\\(?:repos/\\)?[^/]+/[^/]+" . org-sync-github-backend) ("bitbucket.org/[^/]+/[^/]+" . org-sync-bb-backend) ("demo.com" . org-sync-demo-backend))) ;; if you have already loaded org-sync.el, you'll have to add it ;; manually in that case just eval this in *scratch* (add-to-list 'org-sync-backend-alist (cons "demo.com" 'org-sync-demo-backend)) ;; now, in its own file org-sync-demo.el: (require 'org-sync) ;; this is the variable used in org-sync-backend-alist (defvar org-sync-demo-backend '((base-url . org-sync-demo-base-url) (fetch-buglist . org-sync-demo-fetch-buglist) (send-buglist . org-sync-demo-send-buglist)) "Demo backend.") ;; this overrides org-sync--base-url. ;; the argument is the url the user gave. ;; it must return a cannonical version of the url that will be ;; available to your backend function in the org-sync-base-url variable. ;; In the github backend, it returns API base url ;; ie. https://api.github/reposa/<user>/<repo> (defun org-sync-demo-base-url (url) "Return proper URL." "http://api.demo.com/foo") ;; this overrides org-sync--fetch-buglist ;; you can use the variable org-sync-base-url (defun org-sync-demo-fetch-buglist (last-update) "Fetch buglist from demo.com (anything that happened after LAST-UPDATE)" ;; a buglist is just a plist `(:title "Stuff at demo.com" :url ,org-sync-base-url ;; add a :since property set to last-update if you return ;; only the bugs updated since it. omit it or set it to ;; nil if you ignore last-update and fetch all the bugs of ;; the repo. ;; bugs contains a list of bugs ;; a bug is a plist too :bugs ((:id 1 :title "Foo" :status open :desc "bar.")))) ;; this overrides org-sync--send-buglist (defun org-sync-demo-send-buglist (buglist) "Send BUGLIST to demo.com and return updated buglist" ;; here you should loop over :bugs in buglist (dolist (b (org-sync-get-prop :bugs buglist)) (cond ;; new bug (no id) ((null (org-sync-get-prop :id b) '(do-stuff))) ;; delete bug ((org-sync-get-prop :delete b) '(do-stuff)) ;; else, modified bug (t '(do-stuff)))) ;; return any bug that has changed (modification date, new bugs, ;; etc). they will overwrite/be added in the buglist in org-sync.el ;; we return the same thing for the demo. ;; :bugs is the only property used from this function in org-sync.el `(:bugs ((:id 1 :title "Foo" :status open :desc "bar."))))
That's it. A bug has to have at least an id, title and status properties.
Other recognized but optionnal properties are :date-deadline
,
:date-creation
, :date-modification
, :desc
. Any other properties are
automatically added in the PROPERTIES
block of the bug via prin1-to-string
and are read
back by org-sync. All the dates are regular emacs time object.
For more details you can look at the github backend in org-sync-github.el
.
More information
You can find more in the org-sync.el
commentary headers.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK