├── FAQ.md └── README.md /FAQ.md: -------------------------------------------------------------------------------- 1 | # FAQ 2 | 3 | Q: Why would you use this? 4 | A: I don't know, you're the one looking into it. 5 | 6 | Q: No, really, why? 7 | A: You can bootstrap project management of something you're working on 8 | without any dependencies on external software. You can work offline. 9 | You can use whatever tools you want (SublimeText, notepad, ed, cat, 10 | vim..) to manage issues and not be locked into any vendor-specific 11 | tracking software. You can keep track of things you need to do on 12 | as granular a level as you want locally without management complaining 13 | about the number of tickets. You can follow this convention and keep your 14 | issues alongside your code in the same repo. You can trivially define 15 | your own extensions/conventions to add to this since arbitrary files 16 | are permited. 17 | 18 | I don't know you're the one looking into it. 19 | 20 | Q: How do I close an issue? 21 | A: `git rm -r` 22 | 23 | Q: How do I reopen an issue? 24 | A: `git revert` 25 | 26 | Q: How do I rename an issue? 27 | A: `git mv` 28 | 29 | Q: What if issue names conflict? 30 | A: Why are your issue titles generic? If you're using a shared git repo 31 | to manage issues with other people, make sure you pull (and push) often 32 | enough to avoid conflicts and other users are using descriptive issue 33 | titles. 34 | 35 | Q: How do I check the issue creation time? 36 | A: Check the file ctime, or use `git log` 37 | 38 | Q: How do I check the issue last update? 39 | A: Check the maximum file mtime of anything in the issue directory. 40 | (or `git log`) 41 | 42 | Q: How do I see the issue author? 43 | A: `git log` (if it's not tracked, the author is you.) 44 | 45 | Q: How does a team comment on issues? 46 | A: Adopt a convention to use as an extension of this standard and track it 47 | in a git repo. In the unlikely event that this standard becomes popular, 48 | whatever convention is most widely adopted/considered best practice will 49 | probably be incorporated into a future version. 50 | 51 | (Whatever the convention is, `git log` will almost certainly be how 52 | you find the time/author of a comment.) 53 | 54 | 55 | Q: How do I enforce [policy x] for a team 56 | A: Write a git hook. 57 | 58 | Q: This can never work because [...] 59 | A: Okay, so use something that works better for you. 60 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Poor Man's Issue Tracker 2 | 3 | This is a poor man's issue tracker. It's a loosely defined set of conventions 4 | for using the filesystem as an issue tracker. Tools ([such as these](https://github.com/driusan/IssueTrackerTools)) can be written to write 5 | or read or write directories following this convention. Track the whole thing 6 | with git, and you can call it a distributed issue tracker. 7 | 8 | The conventions defined here can be parsed into a database (which should be 9 | gitignored if using something like sqlite) for efficiency of querying in an 10 | http frontend to an issues directory. 11 | 12 | ## Issue Conventions 13 | 14 | There should be a top level directory named issues. 15 | 16 | Any subdirectory of the issues/ directory is considered an issue. The 17 | directory name should be a short human readable description of the issue 18 | and can be considered the issue title. Dashes should be interpreted as 19 | spaces and n > 1 dashes should be interpreted as n-1 dashes when 20 | converting directory name to a human readable issue title. 21 | 22 | You can put any files you want in an issue subdirectory, but there are 23 | some basic conventions that should be followed for the following files 24 | (and you should consider using git annex instead of git for tracking any 25 | large files): 26 | 27 | `Description`: This file contains free form text describing the issue. 28 | It can be interpreted as markdown format. 29 | 30 | `Status`: The first line of this file, after trimming beginning/end of 31 | line whitespace defines the status of the issue. It can be 32 | arbitrary text and the status value is case-insensitive. 33 | 34 | If there is a colon in the text, the part before the first 35 | colon is considered the status, and the part after the value 36 | of the status. 37 | 38 | Some examples statuses might be `Open`, `Assigned:driusan`, or `Wtf` 39 | 40 | Only the first line defines the status, but tools should preserve 41 | the rest of the file when modifying it. A user might manually 42 | include, for instance, information on why this status is defined 43 | for this issue. 44 | 45 | `Priority`: The first line of this file, after trimming beginning/end of 46 | line whitespace, should be interpreted as a number which 47 | defines the Priority of this issue. Higher numbers have higher 48 | priority. Negative numbers (or real numbers) are perfectly valid. 49 | Interpretation of complex numbers is left as an exercise to the 50 | reader. 51 | 52 | Only the first line defines the priority, but tools should 53 | preserve the rest of the file when modifying it. A user might 54 | manually include, for instance, information on why this priority 55 | is assigned to this issue. 56 | 57 | `blockedby`: This subdirectory of an issue contains files where the file 58 | name is the name of some other bug blocking this issue. It can 59 | optionally be a symlink, but it's equally valid to just be an 60 | empty file (or a file containing text, such as a reason why 61 | the other issue blocks.) 62 | 63 | Commandline tools (or http implementations) should ensure these 64 | names are updated in other issues pointing to this if an issue is 65 | renamed. 66 | 67 | `tags`: This subdirectory contains empty files with tags that can be used 68 | to categorize this issue. 69 | --------------------------------------------------------------------------------