Handling Bugs & Features Requests with Github Projects
-
Proposal
- Use two github project boards to track (1) bugs, & (2) feature requests
- The project boards have 'cards', the cards need only be a very short title and then a link to either a corresponding forums post or a github issue.
- The project boards would serve as the 'source of truth' for the lists of feature requests, bugs, and the top-10 of each. Because the board are just placeholders, it is no longer important where the original bug or feature request is located. We still get a single place that lists everything and then links to wherever there is more information. There is no need to move conversations, and we can accept bugs wherever they are posted (whether on forums or github issues or wherever).
Where Help is needed
- (1) Feedback is really appreciated here, please share your thoughts o this proposal
- (2) someone to organize all the existing bugs & features and get them listed and put on the boards
- (3) someone to help identify the top-10 features & bugs
Overview / Background & Context
There is kind of a long story of how TripleA has handled tracking of bugs & feature requests. Cutting to the chase: (1) the solutions we found I don't think are terribly satisfactory. (2) A number of things have changed since TripleA migrated off of SourceForge - there are new options now.
I watched a youtube interview recently with a veteran AAA-game developer. They shared a story of how a team of his set up two white boards, one was the top 10 incomplete features that needed work, the other was the top 10 bugs. He mentioned that this worked really well to help keep focus and get the project through to its final phases. Developers when starting their day essentially looked at either board and then picked what to work on.
Github launched "projects" some years ago, and the "projects" is really an online version of a task-tracking white board (JIRA & Trello are also very similar things & concept). I propose we use a project for tracking bugs and another for tracking feature requests - very similar to the 2 white board setup.
While we do not have a project for 'feature requests', we do already have something set up for bug tracking (https://github.com/orgs/triplea-game/projects/3/views/1 )
How does the a tracking project help us?
I previously pushed that we try to consolidate all bugs to be tracked in one place, a bug tracker. "Github Issues" is a bug tracker, is co-located with the code, and for a variety of reasons that is arguably the ideal bug tracker. (For context, bug trackers need to have a few key things: (a) a way to see what is open/cosed, (b) a way to see details/context without having to read 30 minutes worth of background material, (c) a way to see who is working on something, so it is not picked up by two people).
Though, the forums has a good pulse, is arguably the community, and it is natural for people to want to report bugs (or features) in the forums.
We can use the bug tracker to hide the fact that a "bug" might live in github issues or forums. In short, when an issue is posted to forums, we can create a project-item that simply links to the forums post. If the issue is posted to github issues, the issue can be added directly to the project tracker. Thus, the project tracker does become a single source of truth for "what are the bugs," without having to ask people to 'move' issues they find from forums to github, nor does it require us to put all the bugs in forums as well.
Handling Feature Requests
The best list we had for feature requests was maintained by Ron, in this forum post: https://forums.triplea-game.org/topic/182/guidelines-and-feature-request-list
While that did work well, it was thanks to the efforts of Ron. Of note though, the list is very little more than two things: (A) "title" & (B) "link". Instead of creating line-by-line items in a forum post, we can do that as 'project cards' in a github project.
If we do create the cards on github project that link back to forums, I really like that again we are not moving the conversation from one place to another. While having all communications consolidated is really good and helps efficiency, I've also come to learn that 'moving' a conversation is very impactful (arguably it is more important to not split a conversation than it is to have a consolidated view of issues/features).
Thus, using the project cards as the source of truth - we can somewhat go back to that old school methodology the project used whereby:
(1) a user creates a feature request
(2) the community & developers discuss it, refine it, clarify the request
(3) at the point that the feature request is considered 'legit', is clarified - at that time we create the feature request card to link back to the forum discussion.Final Picture
At the end of the day we would have two github projects (see link above for the link to current 'problem tracker'), one for tracking bugs (aka Issues or Problems), and a second for tracking feature requests. Ideally both projects would give us a view where we can see the full list of "backlog", "top-10", & "done". Developers (and particularly new developers) would only need to look at these two projects to find something to work on. We can make use of tags to try and indicate which would be good for a new contributor. We can also add a lot of people as project maintainers to help with managing the project boards. Further, we would not need to move any conversations, we can keep the discussions wherever they originate. What is more, we no longer need to discourage bug reports from being filed in forums.
Small apologies for not spending a lot of time editing the above! I hope it reads well enough. Please let me know what you think & raise any questions! Of course, if this all sounds good - and if anyone is interested to help organize the bug & feature requests - that help would be incredible to have.
-
@LaFayette
I could help to transfer the list of unresovled rules related issues, that I keep updated.How would the process of transferring work?
That sounds really good and would really help to have an overview of current issues/feature requests, without having redundant information in forums/issues and wherever.
-
@panther Fantastic! There would be two modes of 'transfer'
(1) Github issues - to add a github issue to a project board, it simply needs to be added to the project. That can be done when viewing the issue, note the project area highlighted below in the red box:
(2) Forum posts - when signed in, on the project board (https://github.com/orgs/triplea-game/projects/3/views/1), there is an "add item" at the bottom of each column. After clicking that, it creates a new card. From there, you can add a title to the card (likely to be a copy/paste or a paraphrase of the forum post title).
Next, you'll click the card (EG: https://github.com/orgs/triplea-game/projects/3/views/1/?pane=issue&itemId=66648743) and click 'edit' to update the description, that is where you can put the link (and enclose the link text in angle brackets, eg:
<https://....the..link.../>, that will automatically format it as a clickable link.
It is pretty easy to know if a 'github issue' has been recorded in the feature or problem tracker, it'll be assigned to the corresponding project. For forum posts, perhaps we can add a label to the forum post that it is being tracked. I feel like forum posts probably would benefit by having a link to its tracking card, but that link might get lost if the conversation continues - which makes me think a label on forum posts might be the best way to go to know which ones have been transferred or not. We may want some more labels for forum posts to know which ones are done and which were intentionally not transferred so we don't keep looking at them. I'm not sure what the best approach would be, I think whatever you think might work best -and of course as we put it into practice, it might become more obvious what a better approach would be.
-
We can potentially add tags on the cards too, a 'forums' tag to know more easily it was an issue reported on forums. It's probably not valuable to over-design the process right now (which I am now in danger of doing!) - but at the same time there certainly are some more options to help streamline & organize. Which is to say, we should listen and pay attention to the pain points that we observe - we can then bend the process to help smooth over those pain points.
-
@lafayette
Thank you. I successfully reproduced the steps you described. So count me in. -
@lafayette this all looks pretty good to me happy to help on 2 and 3 if i can
-
@ubernaut Excellent, let me know if you don't have enough permissions on the project to create cards & manage issues.
Sounds like our next steps are to:
- create another project for feature requests
- organize/add cards
If things work out well, we'll then want to update public documentation:
- github issue templates
- forums (categories & any pinned posts)
- website: https://triplea-game.org/
- README / how-to contribute
-
@lafayette not rly sure i understand the project/card system (it def looks good) but will try to check it out asap and get back to u
-
@LaFayette
I have used Trello before.Please setup a project for feature requests.
I have a few feature requests to add to it, and I will go back over the most recent Feature Requests & Ideas forum posts and link them to the project cards.
Also, I will try and rank the top 10 feature request.
So I will be your Project Administrator.
EDIT: To qualify I will be your Feature Requests Project Administrator.
-
@thedog said in Handling Bugs & Features Requests with Github Projects:
So I will be your Project Administrator.
... what I volunteer to be regarding Rules Issues.
So do we need a project for rules related issues - or do we add them to the Problem Tracker Backlog, together with other technical topics?
-
Feature Request board is started:
-
Some Thoughts on the Project Board Organization and the goals of the project boards
How we organize the two boards, feature requests & problems is a bit of an open question.
Needless complexity is not going to help us, perhaps we should stay firm in keeping in mind what our goals are. Essentially we want to organize the issues/topics so a person (developer) does not have to dig through very long lists of many items & generally does not need to spend much effort to find something to work on.
A next important goal, if not more important, is enough organization that maintainers can feel like the various lists are not just a mess, that the important items are indeed visible and easy to see.
It would also be great if average players can look at the lists to see where things are. I think that is a stretch goal.
With respect to these goals & priorities - we need some organization, we need some prioritization, just enough to make sure that the top important things are obvious.
-
@Panther it might make sense to split up the 'problem tracker' columns a bit. I'm a big fan of stack ranking items too, take a card and compare it with other cards to say whether this one should go before or after another card. Priority of bugs/problems should generally be a calculation of impact multiplied by frequency. Rare bugs that kill/crash games, or very frequent bugs are items to go to the top of the list.
With that said, we can use columns to help organize items (rather than using labels, or do both). For example, a column of 'rules problems', and perhaps another for 'fix sooner' to represent the high impact problems that are not rules problems.
@TheDog / @ubernaut , we might want to do similar for feature requests. Things like columns for 'game play efficiency / quality of life', 'map XML features', 'UI enhancements', etc.. That level of organization could very well be overkill and needlessly complex.
When there is a lot of questions on how to do taxonomy of issues/tickets, I often like to try and simplify it to: "fix sooner" & "backlog", where the backlog is organized such that the top 3rd is roughly equal priority, and bottom two thirds are mostly unorganized and are more a big list (where if that top 3rd is worked down, then items from the big list can then be pushed up and organized a bit more).
So, lots of "thinking out loud" ideas here. I think we need to try to start moving items on the boards. Once we have stuff there, it might be easier to see a logical way to sort them. Starting with less I think is going to be more. Perhaps starting with just a "fix sooner" and "fix later" list is good. Going more detailed, to capture different types of work items, could be useful too (but at risk of unnecessary sorting/complexity0
-
@lafayette sounds good to me
-
To be a bit explicit, and a small role-call:
@Panther is going to be organizing the rules related topics.
@TheDog more focused on the feature requests
@ubernaut potentially helping on either/both
We might still need some more help on organizing the (non-rules related) bugs/problems. Overall, perhaps we're already off on a decent start now
-
@lafayette so i look this over again still not sure i understand what i'm supposed to do but maybe it will make sense once i try it
-
@ubernaut said in Handling Bugs & Features Requests with Github Projects:
@lafayette so i look this over again still not sure i understand what i'm supposed to do but maybe it will make sense once i try it
I can offer you to guide you a bit through, once I find some time ...
-
I have enter my top 10 Feature Requests and will hopefully keep that topped up with a curated list for the Devs to pick from.
Currently it looks like this
https://github.com/orgs/triplea-game/projects/9Not sure if people have access to that link so ...
I have ordered the two columns with Top ordered
Top=Hard/Long -- Bottom=Easy/Quick
hopefully that will help a Dev with limited time.
.
Currently even I cannot access that link from here
https://github.com/triplea-game/triplea/projects?query=is%3AopenAs only 2 Projects are listed, @LaFayette please fix
-
@thedog The difference is project can exist at an "organization" level and also at a "repository" level.
https://github.com/orgs/triplea-game/projects/ vs https://github.com/triplea-game/triplea/projects
The repository level projects came first, hence there is that history behind them.
I think we probably should prefer org level projects, but I don't have a very strong opinion on that per se. It is confusing though that projects exist at different 'levels' like that. (In part it's an interface issue, should be more clear what is what)
With that said, no real recommendations here, just hopefully that clarifies what is going on. Happy to tweak things as would be helpful.
-
@lafayette
As GitHub is already hard to navigate for most users, including me, I would prefer if the projects could have a pointer/view to where it currently is now, just like the current problem tracker does.That way when a new user of GitHub looks to get
- Releases - download manually
- Raise an issue
- Look at any Project its all there, or appears to be there
https://github.com/triplea-game/triplea/projects
Appears to more for us usersand the 1st link appears move for Devs, well thats my perception.
