gpm/templates/issues.org

#+Title: Git Project Management Issues
#+Author: Your Name <your email>
#+PROPERTY: Effort_ALL  0:10 0:20 0:30 1:00 2:00 4:00 6:00 8:00
#+TODO: TODO(t) STARTED(s) WAITING(w) | DONE(d) CANCELLED(c)
#+COLUMNS: %38ITEM(Details) %TAGS(Context) %7TODO(To Do) %8ASSIGNEE %5Effort(Time){:}
#+TAGS: bug(b) doc(d)
#+STARTUP: content
#+STARTUP: latexpreview

This is an example on how to organize the issues. The basic usage is quite
simple, only use 3 status (todo, started, done)

The second section "Issues" show a more advanced usage which once you're used to
org-mode shouldn't be too hard to follow.
Mainly the idea is simply to add tags and properties.
You can use tags as github labels.
And think about properties to manages meta datas such as:

- Assignee (who is assignee to an issue)
- Reviewers (who is asked for review)
- 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

* Complex Usage with Review

We will also use the basic but we also consider PR and their review.
So we add a few informatiosn for org-mode typically
we decalre common properties to be used.

#+PROPERTY: ASSIGNEE
#+PROPERTY: REQUESTED_REVIEWERS
#+PROPERTY: REVIEWER
#+PROPERTY: BRANCH
#+TODO: REVIEW(i) | MERGED(m)
# for Reviews
#+TODO: ACCEPTED(a) CHANGE_REQUESTED(c) QUESTION(q) FEEDBACK(f) | REFUSED(r)

** REVIEW Basic review process
   :PROPERTIES:
   :BRANCH:   explain-review-process
   :ASSIGNEE: yogsototh
   :REQUESTED_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/<branch-name>-<reviewer>.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: shubby
   :REQUESTED_REVIEWERS: yogsototh
   :END:
*** ACCEPTED Advanced review workflow explained!
    :PROPERTIES:
    :REVIEWER: yogsototh
    :END:

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.

A simple way to achieve this would be to create a reviews directory:
~mkdir ~/.reviews~

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-capture~ and put the result
in =reviews=.

#+NAME: init-reviews
#+BEGIN_SRC emacs-lisp :results silent
;; (load "../gpm-review-0.0.1/gpm-review.el")
(require 'gpm-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                     :doc:ops:
   :PROPERTIES:
   :ASSIGNEE: yogsototh
   :END:
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

Shubby: @Alex should I write a subtitle?
Alex: @Shubby I think you can"
* Full Professional Usage

Mainly think agile kanban/scrum with QA and Ops team
So we need to think about 3 kind of issues. Epic, user story and task.

# for Epics and User Stories
#+TODO: TO_DESCRIBE(b) IN_PROGRESS(g) TEST(e) | DELIVERED(l)
#+TAGS: epic(e) user_story(u) task(t) qa(q) ops(o)
** if you are fan of scrum / kanban methodology                     :epic:
   Write the detail of the epic. If you are working on writing the epic you
   might put a TODO or WAITING or create
*** Subtask 1 :user_story:
    Describe the feature the user want and create all subtasks as well as a list
    of tests tasks for QA team. If needed add some informations for the ops team
    if they need to change something to deploy it correctly.
**** REVIEW technical task 1                                        :task:
   :PROPERTIES:
   :BRANCH:   tech-task-1
   :ASSIGNEE: yogsototh
   :REQUESTED_REVIEWERS: shubby
   :END:
Describe the technical task.
**** MERGED technical task 2                                           :task:
     CLOSED: [2018-08-30 Thu 12:54]
   :PROPERTIES:
   :BRANCH:   tech-task-1
   :ASSIGNEE: yogsototh
   :REQUESTED_REVIEWERS: shubby
   :END:
***** ACCEPTED Review finished
      :PROPERTIES:
      :REVIEWER: shubby
      :END:

**** REFUSED test by QA                                             :task:qa:
     CLOSED: [2018-08-30 Thu 13:02]
     Describe how to test. If something fail, describe which test is failing,
     etc...

I can't make it work! Please fix it please.

**** TODO deploy a redis instance                                  :task:ops:
*** Subtask 2 :user_story:
**** TODO technical sub task 1                                         :task:
**** TODO technical sub task 2                                         :task:
**** TODO test by QA                                                :task:qa:
     Describe how to test. If something fail, describe which test is failing,
     etc...
**** TODO add a new configuration value                            :task:ops: