Eclectic Media Git eclecticmedia-issue-guidelines / 608dcb0
Updated README, added guidelines.org overview file Ariana Giroux 2 months ago
2 changed file(s) with 83 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
00 This repository outlines guidelines for creating issues in the style of https://eclecticmedia.space/
1
2 Issues on ``https://eclecticmedia.space/`` are created using ``orgmode``. To see the documentation in its truest form, it is recommended you use the same.
3 Due to the use of ``orgmode``, all issues are flexible and plaintext human readable (a must have).
4
5 For more, see ``./guidelines.org``
0 * Introduction
1
2 ** Why =orgmode= for issue management?
3
4 It is the belief of the site's system adminsitrator that any reliance on
5 web technology is a reliance that should be avoided. Web technology
6 requires too many layers of technology to be reliably accessed by anyone,
7 regardless of their access methodology. A key concern for the system
8 administrators is lightweight, simple, and command line oriented solutions
9 to ease developement.
10
11 Enter plaintext issue management.
12
13 Orgmode's use of plaintext formatting and mature command line clients
14 (emacs, vim-orgmode) makes for an ideal candidate in issue management.
15 While other solutions exist, none provide the simplicity that plaintext
16 can offer when integrated fully with the git suite.
17
18 The entirety of the "issue board" can be managed by distributed offline
19 committers via git's "send-mail" functionality, reducing wasted time on
20 waiting for the web to load. This also allows a much more free form method
21 of documenting /issues, bugs, discussions, and more/.
22
23 ** Project issue folder structure
24
25 By convention, contributors to the server adhere to a simple set of basic
26 rules to avoid conflict and enable automation:
27
28 1. All issue/orgmode files should be contained within a folder at
29 ~./.issues/~
30
31 2. An "/issues/" folder should contain an "/index/" orgmode file at
32 ~./.issues/issues.org~
33
34 3. All discussion should be accessible by linking a file within the
35 "/issues/" folder.
36
37 For example, if a discussion over an API spec is growing too large to
38 be easily managed alongside the rest of the project's discussions in
39 the "/issues.org/" file. Where the "/index/" file contain the
40 following:
41
42 #+BEGIN_EXAMPLE
43 * 1. API Spec
44
45 * [-] Consectetur nobis [33%]
46
47 Amet doloremque debitis consequatur modi quasi quis. Eius delectus reiciendis fugit ratione.
48
49 - [ ] Consectetur commodi at aperiam reiciendis mollitia Dicta.
50
51 - [X] Consectetur nisi magni inventore consectetur porro
52
53 - [ ] Dolor quos sequi nihil optio debitis Nesciunt assumenda
54
55 * [ ] Consectetur laboriosam est [0%]
56
57 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
58
59 - [ ] Adipisicing vero fugit itaque animi!
60
61 # AND MORE....
62 #+END_EXAMPLE
63
64 We could then move the previous text into a new file at
65 ~./.issues/api_spec.org~ and replace the text in the "/index/" file
66 with the following:
67
68 #+BEGIN_EXAMPLE
69 * MOVED 1. [[.issues/api_spec.org][API Spec]]
70 #+END_EXAMPLE
71
72 *NOTE: The previous link may or may not link properly.*
73
74 Once the discussion outgrew a single file, it could be further split
75 into chunks, file by file in a new subdirectory. After each section is
76 moved to a new file, its title should be replaced in its original
77 location with a link as above.