Github issues shortened, easy to understand

Developer
,
1

Hey everyone,

I had to condense some of the more recent issues on the github repo.
My apologies to those whose comments and requests were truncated.
What was removed:

  • Conversational phrases
  • Embedded additional feature requests
  • Duplicate information

When creating issues, please keep in mind:

  1. Discussion on github isn’t seen by the community, so decisions are made by the few. So…first have a lengthy discussion on the forum, get community consensus. One person’s idea may need improvement to meet everyone’s needs. Screenshots and descriptions should be posted in forum for vetting.

  2. Developers should be able to easily scan for issues they like and quickly smash them. So …issues should be short, well-defined, and easy to read.

  3. Additionally, If the github issues list were to be treated as our second forum:

  • too much time required to read (and maintain) two forums on same subject
  • difficult to clearly understand what is being requested in github discussions
  • additional feature requests embedded in discussion make the issue too complex to implement
  • important details get “buried” in friendly wordy overhead
  • lack of clarity leads to incorrect code implementations

If we follow these guidelines, where discussion and decisions are on the forum, and use github issues for tersely recording those decisions, then code implementation will be faster and easier.

Thanks to everyone who has contributed to the github repo. It’s important.

1 Like
2

  1. What do we do when someone creates an issue without prior forums discussion? Not that it matters now, but for ex: previously bug reports from the About menu within the program were directed to the Repo issues.

  2. Keeping in mind that it may takes days for others to read the forums… Can we stick to this?

  • Bugs:

  • Users post their questions here on the forum to determine if it really is a bug. Otherwise the issues list will become swamped with noise.

  • If a bug is confirmed they add it to the issues list, and the forum thread will be closed with a link to the issue.

  • Proposals:

  • Users post their proposals on the forum to open discussion. This allows vetting of proposals if they’re relevant for everyone, not just a few. Even if the proposal is helpful for only a few users, then the community will probably be supportive if the case has been presented fully.

  • If the proposal receives enough details and users like the idea, the proposal is added to the issues list and the forum thread is closed, with link to the issue.

1 Like
3

We have a new issue_template.md file to help guide issue creation. Currently this is what users see when they click on the New Issue button:

  • Has the issue been discussed and finalized on the forum?
    If no, return to forum and finalize discussion.
    If yes, enter link to the forum thread on this issue, then enter issue description.

I think it can be improved, but it’s a start!

Remember it may be never for others to read the issue. So far for the past few years we’ve been able to stick to it. Lately though we have a lot of really excited users, so github issues have appeared in conversational format prior to hashing out the details on our current Discourse the forum (current), and years previous we asked people return to the Google group to complete the discussion.

Excitement is great! We don’t want to lose any excitement. Open source communities are good at learning the general process flow and assisting other members with the recommended flow. It’s different for each community.

Since we have so many users that are domain experts in a highly technical field (patternmaking) then discussion can go far and wide sometimes, due to our users’ expectations to completely analyze any given situation (which is good!!!) All options and possibilities are discussed. This is good for the forum but bad for the issues.

Also our community is not only technically inclined but also super friendly (which is great combination) so personal conversations frequently get embedded in the discussions. Again, this is good for the forum but bad for the issues.

So @Douglas your policy statement follows our “unofficial” guidelines that we’ve been following all along. I guess it’s time to add this info to a FAQ on this forum and on the repo. And to improve the new issue_template.md file.

Thanks for codifying the decision tree!

1 Like