Formalize rules for organizing repository and add bots to help

[stalgiag]

This is an issue to track and propose formal rules for the management of issues. Currently it can be a bit difficult for the maintainers to prioritize the issues, to know when and why an issue is stale, to triage issues, and guide new contributors through the contribution process. I think that some of this might be made easier through a formalized set of rules and some automated oversight of said rules.

Some examples of rules could be:

1. All issues must have at least two labels, subarea (core, image, etc) and issue-type (discussion, bug, feature request).
2. All bug report issues must post example code.
3. At least one person must be able to reproduce a bug within a certain period.
4. All reproducible bug reports and agreed-upon feature requests must have an assignee within 30 days.
5. All pull requests must be associated with an issue.

Then the example automation would be:

1. Users are heavily encouraged to label issues when posting and unlabeled issues are automatically labeled based on keywords or the way the template is filled out. Issues that aren't able to get labels this way have a "needs manual labeling" label applied.
2. If sample code isn't provided when an issue is marked as bug, then a bot automatically requests example code. If the issue writer does not add code within 14 days, the bot posts a friendly message and closes the issue. Will automatically reopen with response.
3. All bug issues that fulfill the above criteria close after 30 days unless someone is able to reproduce. This can potentially be confirmed by the bot with a keyword search.
4. If after 30 days, there is no assignee, then one of the maintainers will automatically be assigned based on labels. Maintainers would agree on labels that they are willing to oversee. Luckily Github just made a change that allows all users that have commented on an issue to be assigned to that issue, so now contributors that are not org members can be automatically assigned if they comment something like "I'd like to handle this one", "Please assign me to this issue", etc etc.
5. If a pull request doesn't have an issue associated with it, a message is posted in the PR, and a 'work-in-progress' label is added automatically.

The above examples are in no way set in stone. These are just to jumpstart some thinking about the scope of codification and automation that we might want to consider.

I know that automation can have very mixed results on the culture of a repository. I have no interest in adding changes that make this space feel alienating, cold, or convoluted. The goal here is to come up with ideas for how we can formalize the organization, prioritization, and assignment within the project so that all decisions feel more transparent.

[lmccart]

@stalgiag I think these are a great starting point.

• We may want more than 30 days for some of these, I'm thinking of the assignee one specifically.
• Maybe: If an issue with an assignee has no activity for 30 days, it asks the assignee if they'd still like to work on it. If no response, assignee is removed.
• This could be a great topic to discuss at the contributor's conference.
• Whenever we do implement, we may want to roll them out iteratively in small batches, rather than adding a lot of automation in one go.

[outofambit]

@stalgiag I think this is great! Some thoughts on these individual proposals. Happy to discuss more!

All issues must have at least two labels, subarea (core, image, etc) and issue-type (discussion, bug, feature request).

I LOVE this one. I find labels super helpful in finding and exploring issues.

All bug report issues must post example code.

This would be nice, I don't really know how to enforce that though.

At least one person must be able to reproduce a bug within a certain period.

I worry about bugs that are valid and documented, but haven't been reproduced due to people's availability. One thing we do in desktop/desktop is use a more-info-needed label to mark issues that are bugs but need well, more info. Perhaps we could do something like that? (We do go through and close more-info-needed issues if the reporter hasn't replied in a couple weeks.)

All reproducible bug reports and agreed-upon feature requests must have an assignee within 30 days.

I also worry about people's availability for this one. Plus, having unassigned issues are opportunities for new contributors to get involved!

All pull requests must be associated with an issue.

👍

Maybe: If an issue with an assignee has no activity for 30 days, it asks the assignee if they'd still like to work on it. If no response, assignee is removed.

I think something like this would be great so we have opportunities for new people to get involved.

[stalgiag]

I want to leave this discussion dangling for a bit longer. So I am going to push it back to the 1.0 milestone.

Any thoughts on organization and governance for this repository are very welcome. You can respond to some of the suggestions already brought up or just throw out altogether new ideas/opinions.

I will try my best to compile and track all of the ideas and opinions and reduce them to a few actionable items over the next month.

[stalgiag]

Coming back around to this, I have been flip-flopping on whether these tasks are better approached with Github Actions or bots. After further research, I am feeling fairly certain that bots will be better suited to repository organization. Sorry for the runaround @outofambit !

For most of what we would like to do, there are more stable existing bot solutions than there are github action examples. Actions would also potentially require a certain amount of maintenance. Happy to hear and discuss differing opinions!

With the bot approach in mind again, I have been looking over various probot apps. I've had positive experiences with several of these bots in the past. So based on looking over I have outlined several bot additions based on prior discussions and several more that require further discussion:

Based on previous discussion

• Automatically Label Issues:
  • Label based on keyword search in title and body
  • Add 'Triage' label to issues with no label, Remove 'triage' label once labeled
  • Some experimenting will need to be done to see how these two play with each other
• Automatically manage assignees:
  • First person to request to work on issue gets assigned. This bot does this, but its usage isn't ideal. Might require custom solution or forking an existing bot.
  • Ping assignee after period of inactivity, if no response assignee is unassigned to issue

New proposals based on bot research

• If an issue has the 'more-info-needed' label applied to it for more than certain number of days (30?), it is automatically closed. Bot available here.

I can start adding and setting up bots once there is final agreement on any of the above. Thanks!

[lmccart]

Sounds good! A few thoughts:

• Can the "triage" label be something like "please-help-label" etc? I think some people may not know what "triage" means and may be hesitant to remove the label or add others.
• Question: can anyone be auto-assigned by the bot, or do they need to already be a part of the team that has contributor access to the repo? If so, is there a way to automate this step too, adding people as needed?

[stalgiag]

• Can the "triage" label be something like "please-help-label" etc? I think some people may not know what "triage" means and may be hesitant to remove the label or add others.

I fully agree. triage is an obtuse word. Quickly glancing at the bot code it looks like it allows you to set a custom label in the settings.

• Question: can anyone be auto-assigned by the bot, or do they need to already be a part of the team that has contributor access to the repo? If so, is there a way to automate this step too, adding people as needed?

Github recently modified the rules so that any commenter on an issue can be assigned to the issue. That said, I haven't been able to find a bot or action that does this in an ideal way. The bot that I linked in my prior comment, pro claim, requires the person to write '@proclaim claim' in a comment which is a non-starter in my opinion. I am still searching for other options/approaches.

[gr2m]

Hey there 👋 I'm one of the Probot maintainers and also maintain the underlying JavaScript toolkits that for GitHub's APIs. I'm a big fan of the p5.js community. If there is something I can help with please let me know!

GitHub Apps are great if you need an immediate response. GitHub Actions usually take a minute to boot up. Apps are also easier to debug in my experience, GitHub Actions can be something of a black box, and iterating on a bug fix can be time consuming.

On the other side, Actions are easier to collaborate one, they are directly part of the code base. You don't need to worry about deployment and don't need to worry about monitoring.

If there is anything you want to run on a schedule, then Actions are definitely preferable. But you can also GitHub apps from an action, e.g. load all issues from all repositories the app is installed on, look for labels, add comments, etc. It's an interesting hybrid solution.

If you have a process you'd like to automate and are not happy with existing solutions out there, I'm happy to see if I can help building it for you, or adopting an existing solution.

[stalgiag]

Thank you so much for the offer @gr2m !

We have been talking about ways to get more people involved in specific discussions on the repo. The idea is that a large portion of our community doesn't use github consistently, and it would be great to be able to poll opinions, generate discussion, and encourage contribution through another platform such as Twitter.

With that in mind, we thought it might be cool to automatically create a Twitter poll through the p5 twitter when an issue @ notifies a bot along with a set of options. Something to the effect of:

@twitter-poll-bot make a poll. prompt: When print() is called without any arguments, the browser tries to print the sketch out on paper. This causes confusion so we want to try renaming the function. What do you think would be best? options: a: console() b: printToConsole() c: log() and rename the existing logarithm function

There are a number of different design considerations. Does a user need push authorization to make a poll? Is it possible to vote or display results within github issue as well?

@lmccart found this example that you made that shows communication between github and twitter using actions. This suggests more of a pull request based approach to posting on twitter. This also seems feasible, and opening a tweet pull request could be part of a manual procedure.

Anyways! I am getting ahead of myself. If you are interested in working on a project like this with p5 as a launch case, or just helping us figure out how to make twitter-together work best for our needs, we can open a new issue to discuss. Thanks either way!

[gr2m]

That sounds fun! I think adding it as a feature to https://github.com/gr2m/twitter-together would be a good approach from my side. If it doesn't end up working well you, then we can still try a different approach.

I'll have a look at the APIs for creating polls. I'm in Germany with my family and mostly offline until January, I'll have a look then. Would that be okay with you?

[lmccart]

hey @grege2 I think that all sounds great! very excited about this idea

[stalgiag]

Amazing! Thank you so much @gr2m !

[gr2m]

I've created an issue to add support for polls at https://github.com/gr2m/twitter-together/issues/79, I'd suggest to discuss details there and leave this thread to discuss further bots ideas.

[gr2m]

Talking about other bot ideas. I'm very interested in enabling editorial contributions to Open Source projects. I've seen it be a huge part of a projects success, especially with http://hood.ie/.

twitter-together is one of the ideas we had back then, everyone can now suggest tweets. To lower the barrier further to editorial contributors which might not be familiar with GitHub, I'd like to create a custom UI for twitter-together, that is tailored to the process of suggesting and reviewing tweets.

Another idea I had is https://github.com/octonews/octonews. Think Hackernews/reddit, and using GitHub as the backend for data persistance and authorization. I think a community is defined by common interests, and suggesting news items that might be interested to follow p5.js users/contributors is a great path for contributions that is not code.

When I created octonews, the available APIs where not sufficient, but it should be possible now. If that is sth that would interest you, I'd give it another look, I've been waiting for a good reason.

But let me know what ever would help p5.js right now, I'm happy to help as good as I can, also happy to coach others so more people will be able to build this kind of automation

[stalgiag]

Hi @gr2m that is really interesting! I am going to move that to a new thread since it seems like a large topic in and of itself.