A dive into needs and wants and whys.
Also see:
- Introduction – Lets make a bug tracker!
- Background – It’s not really a bug tracker!
Time to get to some use cases, requirements, needs, wants, and technology. As mentioned in the last post, I need something to replace the features we currently have in Lotus Notes. While this is a project inspired by issues at work, and I hope it will be used there, the actual needs and requirements are coming from me. Not everyone in my group would agree with what I am calling requirements. Some of my requirements are there because of specific pain points I am having, but which do not really bother others. But hey, it’s my project, so they don’t get a say.
With that, it is time for a
Disclaimer: The postings on this site are my own and don’t necessarily represent my employer’s positions, strategies or opinions. Opinions and ideas expressed here are mine and mine alone.
Objectives
The pr1mary objectives are:
- Increase visibility with ease of access (web interfaces or simple app)
- Integrate with other existing systems (Perforce, Plone, Active Directory, release processes)
- Preserve and or migrate sixteen years of history (old bugs, api discussions, etc.)
- Support existing workflows (fast ramp-up for users)
- Minimal impact on schedules (get it up and running without anyone noticing until it is done… hi boss….)
That’s about it really.
High Level Functionality
Quick summaries of the functionality we will dive into.
- Issue/Bug Management – Our needs are very simple, but specific. Multi-Project, RSS, large files, and read/unread markers being chief among them. The biggest issue here is how we manage the forks. Each bug/issue will have a status in multiple forks. There are multiple ‘active’ forks which need to have their status set. As new forks are made, the system needs to know about them. Archived forks are not set on the bug. A bug is not fully closed until it is closed on all forks. Very few issue management systems do this out of the box, though many support similar work flows.
- API/Code Review - Nicely color coded diff of changes to the API with the ability to make comments on the changes, and have multiple versions of the multi-file changes. This is key for the API review. General code review is secondary. This need not be fully integrated into Perforce via triggers. That option would be nice, but for the API review, it would be better to submit a changeset via some script (*cough* upload.py. gee… what ever system could I be thinking of for this….) Essentially we need a way to review patches which are not checked in anywhere. It would be nice to review changes which are pending or already submitted as well, but that is a want, not a need; we have that functionality in another trigger system already.
- Discussion Threads – Similar to a bulletin board, but with thread and read/unread requirements. The key features from Lotus Notes are the overview listing with read/unread status. The ‘topic’ can be changed and is modified over time with a change history. Underneath in the main list view are threaded responses. Everything has read/unread markers. Think of a threaded e-mail archive, where the initial e-mail can be edited with a change history. BBS systems come close but miss the mark on the key requirements.
- Static Release HTML Help/Docs – (sideline work) Technically not something that is in Notes and already exists internally, but we need to integrate with it cleanly so mentioning it. Adding an app to smartly serve up static files are set locations would be simple enough to add and would replace some fancy apache rewrite rules.
- Interview Management – (bonus work) special discussion system for managing resume’s, code problem solutions, etc. Has special permission requirements, and voting (+1, +0, 0, -0, -1)
- Machine Management - (bonus work) very very simple app for tracking who has what hardware specs on their machines. Not asset management. Just useful for when we have budget to get new hardware, or when a bug appears to be hardware specific.
Some of this could be moved into Plone, or just abandoned. Much of the project management occurs in Plone and integrates across projects. Different projects use different tools, but everyone integrates at the Plone level. One restriction on the Plone side is, because many groups are using it, there is a very high barrier to adding new functionality or special customization. Also we do not have the option to go with a cloud hosted solution like some groups, due to our access to medical records. Just the access to such records means we can not risk it.
Issue/Bug Management
Requirements:
- Active Directory Integration
- Perforce Integration (very minimal)
- P4M Fork integration (one bug, many forks)
- P4M Version integration (is the format valid)
- RSS Feed (cheap Plone Integration)
- Large file support
- Milti-Project
- Read/Unread Marking
- Filters (open, closed, owned by, etc.)
- Searchable
Nice to have:
- Strong Perforce Integration, Checkin’s and Changesets (i.e. see the code from the issues)
- Strong P4M Fork/Version integration (does a fork/version exist, active forks, etc.)
- Smart links (turn @34245 into a link to the changeset, etc)
- Colorized source code diffs
- Nice WYSIWYG Editing instead of some wiki markup
- Custom reports, queries.
API/Code Review
There is a different between how we handle the API review than other code reviews. We have a requirements, and proposals. This is can be a many-to-many relationship, but usually is just one-to-one, or occasionally one requirement to many implementation proposals. Sometimes a bug will be referenced as it may require an API change to fix. Often it is a client which will submit a requirements document, which then gets refined.
Requirements:
- Active Directory Integration
- Multi-file changesets
- Colorized changes
- Full and partial change context
- Multiple revisions of a changeset (i.e. one proposal, multiple changesets)
- Requirements document support w/ linkage to proposal
- Change history on requirements document
- Clear history on the changes to the item being reviewed
- Good comment system (duh!)
- Integration with bug/issue system (may just be a hand generated link)
- RSS
Nice to have:
- P4M Integration (submit a changeset from P4M)
- Perforce Integration (Code review of already submitted changes)
- Nice WYSIWYG Editing instead of some wiki markup
- Custom reports, queries.
- Read/Unread markers (this might be moved to a requirement)
- Searchable
Discussion Threads
Discussion threads are interesting in that they closely resemble the functionality in a BBS system, but with some very important differences. The initial topic post is edited with a change history, and then there are threaded comments below. The threaded comments are their own posts. The best way to think about it is your standard mailman archive thread view, but where the author of the initial e-mail can go back and edit their post, and the responses can have different titles. Each entry has it’s own read/unread state. This could be achieved in Plone with a single page with change history and threaded comments except that the comments are at the bottom of the post, do not have read/unread state, and can not be listed as part of an overview tree/list. So they are really nothing like that
Which is why it is hard to find something which supports this mode of discussion we are so used to in Notes.
Requirements:
- Active Directory Integration (why do I keep listing this?)
- Multiple ‘boards’ or whatever (multiple databases in Noted language… just call it Multi-Project…)
- Topic listing with responses all in one list, with thread indentation (needs a picture to describe)
- Change history on Topic level posts
- RSS
- Read/Unread Marking
- File Attachments
- Filters (by date, person, etc)
Nice to have:
- Smart links (turn @34245 into a link to the changeset, etc)
- Colorized source code diffs
- Nice WYSIWYG Editing instead of some wiki markup
- Custom queries
- Searchable
Interview Management
This is a fun one. It is just a very simple Notes discussion database (actually all of these except the bug management is just a simple notes discussion database), with some extensions for voting. When a resume is approved via triage, an entry is added with it attached. We vote on resume’s with a comment. We decide who gets a phone call from these votes, and then people are assigned to make the calls. There is a ‘response’ made to the resume with notes from the phone interview. If the phone interview goes well we send out a programming test. We wash and test the response program. It gets posted unwashed as a response to the resume. The washed version with comments and notes is posted as a response to the unwashed version. Then bring the person in for the real full group interview. Then we try to hire that person. Whenever we are done with the resume, it is ‘archived’ with these notes where only the manager can see it. Very simple and a quick app to write.
Requirements:
- Active Directory Integration (blah blah blah…)
- File attachments
- Ability to ‘archive’ entries to be seen only by manager
- Voting by group members (+1, +0, 0 -0, -1) with comment.
- Status (voting, needs phone interview, waiting for program, etc…)
- Assign person to phone interview/code review
- Read/Unread Marking (see a theme here?)
- Filters (those which I have not voted on yet, needs votes, needs votes by person, a few others)
Nice to have:
- Multiple repositories for different groups (call it Multi-Project)
- Colorized source code?
- Nice WYSIWYG Editing instead of some wiki markup
- Searchable
Machine Management
It’s just a simple table with change history!!! Bah, create a Plone page and be done with it! Why is this still in Notes?
The Big Picture
Really everything currently in Lotus Notes, sans the bug tracker, is based on the basic Notes discussion database. It is best to look at all of these existing pieces of functionality and see if the lines drawn between them are real or artificial. What I mean by that is, much of the code commentary need not be done in discussion threads, but instead as part of a generic code review application. The distinction between API review and code review is important due to who gets input and when, but not much beyond that. The discussion threads are a catch all for many different types of design resolution that do not fit in the API discussion, or the bug tracker. Plone is most likely the best place for much of what is currently in the discussion database, with the code, and file format stuff moving to a code review app. The machine management database is nothing but a poorly implemented Plone page with a table. The real things which are needed are a strong issue tracker, a powerful and configurable code review tool, and a very simple voting app for resume’s (another voting app? *sigh*).
So next up is evaluating existing technologies to figure out which fit best, while taking into account both the background and the big picture. Just in time for me to go back to work in a few hours too… So much for getting it done over vacation. Failure #1 took long enough.
