From 47d8f2b194e746f083614768992eef38c912876f Mon Sep 17 00:00:00 2001 From: "Yann Esposito (Yogsototh)" Date: Tue, 28 Aug 2018 22:52:30 +0200 Subject: [PATCH] Updated the templates with more explanations. --- README.org | 2 + gpm | 9 ++-- templates/issues.org | 105 ++++++++++++++++++++++++++++++++++++++----- templates/review.org | 20 +++++++++ templates/wiki.org | 19 ++++++++ 5 files changed, 141 insertions(+), 14 deletions(-) create mode 100644 templates/wiki.org diff --git a/README.org b/README.org index 807c2ce..7f71e29 100644 --- a/README.org +++ b/README.org @@ -3,6 +3,8 @@ * Goal +Principle: put project management info along the repository not in some DB. + The goal is to have most features that github provide but using only text files and git. Typically solve the problem that github is fully centralized. diff --git a/gpm b/gpm index 44b87ea..95b556a 100755 --- a/gpm +++ b/gpm @@ -24,16 +24,19 @@ debug cmd = do initIssues :: IO () initIssues = do echo "* issue.org" - output "issues.org" (input ("templates" "issues.org")) + input ("templates" "issues.org") + & output "issues.org" initDocs :: IO () initDocs = do echo "* wiki.org" - output "wiki.org" (input ("templates" "wiki.org")) + input ("templates" "wiki.org") + & output "wiki.org" initReview :: IO () initReview = do let fic = "reviews" "write-contributing-yogsototh.org" mktree "reviews" putText $ format ("* "%fp) fic - output fic (input ("templates" "review.org")) \ No newline at end of file + input ("templates" "review.org") + & output fic \ No newline at end of file diff --git a/templates/issues.org b/templates/issues.org index 31890a1..a2fa19b 100644 --- a/templates/issues.org +++ b/templates/issues.org @@ -4,7 +4,9 @@ #+PROPERTY: ASSIGNEE #+PROPERTY: REVIEWERS #+PROPERTY: BRANCH -#+SEQ_TODO: REVIEW(r) FEEDBACK(f) TODO(t) STARTED(s) WAITING(w) | DONE(d) CANCELLED(c) DEFERRED(f) +#+SEQ_TODO: FEEDBACK(f) TODO(t) STARTED(s) WAITING(w) LGTM(l) | DONE(d) CANCELLED(c) DEFERRED(f) +#+SEQ_TODO: REVIEW(r) | MERGED(m) ABORTED(a) +#+SEQ_TODO: ACCEPTED(l) CHANGE_REQUESTED(c) | REFUSED(r) #+COLUMNS: %38ITEM(Details) %TAGS(Context) %7TODO(To Do) %8ASSIGNEE %5Effort(Time){:} #+TAGS: bug(b) doc(d) ops(o) @@ -23,23 +25,70 @@ And think about properties to manages meta datas such as: - branch (the branch asked for a review before merge) * Basic Usages + +The basic usage is to simply create the todo list. The reviewers could simply +add sub items to provide remarks or even other todos. + ** TODO Do thing 3 ** STARTED Do thing 2 ** DONE Do thing 1 + CLOSED: [2018-08-28 Tue 22:37] * Issues -** REVIEW Write a CONTRIBUTING file :doc: + +If you use ~org-sort~ it will put the REVIEW task on top. +Then FEEDBACK (when you simply need to ask questions). + +** REVIEW Basic review process + :PROPERTIES: + :BRANCH: explain-review-process + :ASSIGNEE: yogsototh + :REVIEWERS: shubby + :END: + +So basically the reviewer should write his review here. As the reviewer should +switch branch to the working branch the =issues.org= file won't be easy to +reach. + +So it is up to the user to create a file =~/.reviews/-.org= +The reviewer then will only need to write down its remarks. +To make things easy you can link the files with their lines using +=file:path/to/file:::NNN=. + +Once the review is finished. The reviewer simply need to: +1. switch to the =gpm= branch +2. copy the review file into the =reviews/= directory +3. make a commit aboute the finished review. + +The contributor will then be able to copy the content of =reviews/= into +=~/.reviews/=, switch to the branch to be merged, read the review, make fixes, +add comment to the review files, etc... + + +*** ACCEPTED Review finished + :PROPERTIES: + :REVIEWER: shubby + :END: + +Please change something + +edit: switched from CHANGE_REQUESTED to ACCEPTED! + +**** FEEDBACK Changed! + +** MERGED Write a CONTRIBUTING file :doc: + CLOSED: [2018-08-28 Tue 22:51] :PROPERTIES: :BRANCH: write-contributing - :ASSIGNEE: dave + :ASSIGNEE: shubby :REVIEWERS: yogsototh :END: -*** FEEDBACK yogsototh's review 1 +*** ACCEPTED Advanced review workflow explained! :PROPERTIES: :REVIEWER: yogsototh :END: -A simple way to write and read review is to use ~org-annotate-file~. +A simple way to write and read review is to use ~org-capture~. It will create a file with links to the file your are inspecting in emacs without modifying the file. @@ -49,7 +98,7 @@ A simple way to achieve this would be to create a reviews directory: Then in the next section Use =C-c C-c= to execute that and so you'll see all annotations. -Mainly the reviewer only need to use ~org-annotate-file~ and put the result +Mainly the reviewer only need to use ~org-capture~ and put the result in =reviews=. #+NAME: init-reviews @@ -59,21 +108,55 @@ in =reviews=. (org-with-point-at org-babel-current-src-block-location (org-entry-get nil prop-name t))) -(defun start-review () +(defun gen-review-file-name () (let* ((branch (get-prop "BRANCH")) (reviewer (get-prop "REVIEWER")) - (review-file-name (concat branch "-" reviewer ".org")) + (review-file-name )) + (concat branch "-" reviewer ".org"))) + +(defun start-review () + "to be called at the beginning of the review" + (let* ((review-file-name (gen-review-file-name)) (review-dir "~/.reviews/") (local-review (concat "file:../reviews/" review-file-name)) (global-review (concat review-dir review-file-name))) (url-copy-file local-review global-review) - (setq org-annotate-file-storage-file global-review))) + (setq org-default-notes-file global-review))) + +(defun end-review () + "to be call when the reviewer ends its review." + (let* ((review-file-name (gen-review-file-name)) + (review-dir "~/.reviews/") + (local-review (concat "file:../reviews/" review-file-name)) + (global-review (concat review-dir review-file-name))) + (url-copy-file global-review local-review) + (setq org-default-notes-file global-review))) #+END_SRC +1. Start by using =C-c C-c= here. +2. Switch to the issue branch. +3. If you just want to read the review open the =(gen-review-file-name)= +4. If you want to add a remark use =org-capture= to open the org file that will + contain your remarks with a link to the line and file. + I think to make it easier all member of the team should put their projects + in the same place. Typically =~/dev/project-name=. + + +#+BEGIN_SRC elisp +(concat "[[~/.reviews/" (gen-review-file-name) "]]") +#+END_SRC + +#+RESULTS: +: [[~/.reviews/write-contributing-yogsototh.org]] + #+BEGIN_SRC elisp :results silent (start-review) #+END_SRC +#+BEGIN_SRC elisp :results silent +(end-review) +#+END_SRC + ** TODO [#B] Write a tutorial :doc: Should contains a complete tutorial ** WAITING [#A] Write Install section in README :ops:doc: @@ -84,6 +167,6 @@ Explain how to install the project ** DONE Write README file :doc: The goal is to write a text file with all informations about the project -Dave: @Alex should I write a subtitle? -Alex: @Dave I think you can" +Shubby: @Alex should I write a subtitle? +Alex: @Shubby I think you can" diff --git a/templates/review.org b/templates/review.org index e0e6792..036d27a 100644 --- a/templates/review.org +++ b/templates/review.org @@ -2,3 +2,23 @@ Remove the direct usage of the file inside and prefer to load templates. If possible compressed one. + +#+BEGIN_SRC elisp +(org-remember-insinuate) +(define-key global-map "\C-cr" 'org-remember) +(setq org-remember-templates + '(("Code Review High" ?h "* TODO [#A] %?\n %i\n %a" "~/Review.org" "Issues") + ("Code Review Medium" ?m "* TODO [#B] %?\n %i\n %a" "~/Review.org" "Issues") + ("Code Review Low" ?l "* TODO [#C] %?\n %i\n %a" "~/Review.org" "Issues") + ("Code Review Question" ?? "* TODO %?\n %i\n %a" "~/Review.org" "Questions"))) + +(defun my/linenum() + "Use line number as the file linking item" +;; Optionally, predicate this technique to +;; only certain modes +;; e.g. +;; (when (eq major-mode 'cperl-mode) ... + (number-to-string (org-current-line))) +(add-hook 'org-create-file-search-functions + 'my/linenum) +#+END_SRC diff --git a/templates/wiki.org b/templates/wiki.org new file mode 100644 index 0000000..5816dcf --- /dev/null +++ b/templates/wiki.org @@ -0,0 +1,19 @@ +#+Title: Git Project Management Wiki +#+Author: Your Name + +Put all documentation here. +If the documentation start to grow too much. +Do not hesitate to create directories and link those file in this +main entry point. + +* Project + +** Description +** Contribute +*** Issues +To write a new issue switch to the ~gpm~ branch and add it to ~issues.org~ file. +*** Code Review +To write a code review for the branch ~foo~ if you are the user ~johndoe~ simply create a +file named ~reviews/foo-johndoe.org~ in the ~gpm~ branch. + +To help you write your review you should use [[https://orgmode.org/manual/Capture.html][org-capture]]