Eclectic Media Git eclecticmedia-issue-guidelines / master guidelines.org
master

Tree @master (Download .tar.gz)

guidelines.org @masterraw · history · blame

* Introduction

** Why =orgmode= for issue management?

   It is the belief of the site's system adminsitrator that any reliance on
   web technology is a reliance that should be avoided. Web technology
   requires too many layers of technology to be reliably accessed by anyone,
   regardless of their access methodology. A key concern for the system
   administrators is lightweight, simple, and command line oriented solutions
   to ease developement.

   Enter plaintext issue management.

   Orgmode's use of plaintext formatting and mature command line clients
   (emacs, vim-orgmode) makes for an ideal candidate in issue management.
   While other solutions exist, none provide the simplicity that plaintext
   can offer when integrated fully with the git suite.

   The entirety of the "issue board" can be managed by distributed offline
   committers via git's "send-mail" functionality, reducing wasted time on
   waiting for the web to load. This also allows a much more free form method
   of documenting /issues, bugs, discussions, and more/.

** Project issue folder structure

   By convention, contributors to the server adhere to a simple set of basic
   rules to avoid conflict and enable automation:

   1. All issue/orgmode files should be contained within a folder at
   ~./.issues/~

   2. An "/issues/" folder should contain an "/index/" orgmode file at
   ~./.issues/issues.org~

   3. All discussion should be accessible by linking a file within the
   "/issues/" folder.

      For example, if a discussion over an API spec is growing too large to
      be easily managed alongside the rest of the project's discussions in
      the "/issues.org/" file. Where the "/index/" file contain the
      following:

      #+BEGIN_EXAMPLE
      * 1. API Spec

        * [-] Consectetur nobis [33%]
            
            Amet doloremque debitis consequatur modi quasi quis. Eius delectus reiciendis fugit ratione.

            - [ ] Consectetur commodi at aperiam reiciendis mollitia Dicta.

            - [X] Consectetur nisi magni inventore consectetur porro

            - [ ] Dolor quos sequi nihil optio debitis Nesciunt assumenda

        * [ ] Consectetur laboriosam est [0%]
            
            Ipsum ut autem officiis optio ratione fugit eos voluptas Fugit quis modi ex suscipit ipsum Magnam quia hic dolore amet cum Earum voluptatem consequuntur rem ea officia? Aspernatur modi ratione

            - [ ] Adipisicing vero fugit itaque animi!

      # AND MORE....
      #+END_EXAMPLE

      We could then move the previous text into a new file at
      ~./.issues/api_spec.org~ and replace the text in the "/index/" file
      with the following:

      #+BEGIN_EXAMPLE
      * MOVED 1. [[.issues/api_spec.org][API Spec]]
      #+END_EXAMPLE

      *NOTE: The previous link may or may not link properly.*

      Once the discussion outgrew a single file, it could be further split
      into chunks, file by file in a new subdirectory. After each section is
      moved to a new file, its title should be replaced in its original
      location with a link as above.