Maintainer Tooling Discussion

[jtannas]

Making a thread here for discussing different things we can do to make maintaining the project less time consuming.

Ideas:

• Add a SECURITY.md file for reporting vulnerabilities to head off tickets like Found a possible security issue #135
• Add a rubocop.yml to keep everyone on the same page for project styling; lint & autocorrect PRs
• Add in spellchecker (cspell?) for PRs
• Add https://github.com/marketplace/stale to help keep stale issues under control
• Are the issue templates working? I don't see anything come up when creating a new template. Assuming they're broken:
  • Add in a template chooser https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#configuring-the-template-chooser
  • Create issue forms (or wait until beta is complete?) https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms
• Set up a project wiki with an FAQ page; Split the README into wiki pages
• Set up GitHub Discussions so that we can focus the "Issues" section on concrete issues
• ???

[BookOfGreg]

• Add Security tooling #491 - We need to discuss the content of this file, generally it's expected that there's an email to handle this privately, however given the length of time it took me to get back in the game, what kind of guaranteed can we make?

[BookOfGreg]

• stale-plan #492 - This one should be fairly straight forward. Stale is pretty sensible to me, shame to loose people's good content but there is a limit of what's useful and what will reasonably be gotten to. Discuss in the PR thresholds and message.

[BookOfGreg]

• I've made a discussion section. I've never used one before but happy for others to do so. Hopefully this will help us make and keep this a vibrant place.

You can find it here: https://github.com/rswag/rswag/discussions

[jtannas]

Thoughts on opening up a wiki?
I'm seeing some common threads in the tickets that would fit well into an FAQ section.

• How can split my swagger_helper definitions across multiple files?
• Why is this test passing when there are additional properties?
• Why is this test passing when there are missing properties?
• How to create proper :array parameters #256

They could go into the README but it's getting pretty unwieldy with how long it is

[jtannas]

Related: can I please get a documentation label for keeping track of things to add to an FAQ?
https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels#creating-a-label

[BookOfGreg]

Slowly working through these suggestions, hope you don't mind my pace, you seem to be tracking a little faster than I am 😆 . Do you have any thoughts on a good async communication tool? Team discussions in the org might do it but not used that before either.
Edit: Think at one point @sergioisidoro mentioned about slack or discord, hope I'm not mis-remembering, have a preference?

[sergioisidoro]

I've seen most of other open source projects using Discord for this purpose. So I would lean towards that one.

However I'm second guessing myself about having some sort of chat, because I don't have the availability to reply to things synchronously. So maybe these github discussions for now would be best?

[BookOfGreg]

I think you should have permission to open a Wiki up yourself. The Org settings don't restrict it as far as I can tell but please correct me if I'm wrong there.

I do wonder if the content is better as a GitHub page, I've seen a number of other repos have good GH Pages content for their documentation so I would think that might be the better kind of content, trouble is that needs write access and fairly high-quality content. Wiki or GH Pages?

[BookOfGreg]

Finally got around to making a very basic logo. Anyone who is a designer PLEASE SEND HELP. In the meantime I hope this is OK.

Edit: as you might be able to tell, I am not a professional graphic designer and should never be allowed near the front-end.

[jtannas]

I think you should have permission to open a Wiki up yourself. The Org settings don't restrict it as far as I can tell but please correct me if I'm wrong there.

I'd need access to https://github.com/rswag/rswag/settings to enable that feature and it's 404'ing me so it needs more access than I have.

I do wonder if the content is better as a GitHub page, I've seen a number of other repos have good GH Pages content for their documentation so I would think that might be the better kind of content, trouble is that needs write access and fairly high-quality content. Wiki or GH Pages?

GitHub pages are nicer but Wiki is much less work. My priority right now is to get caught up on the backlog, so I lean towards Wiki to start. Pages can come later when there's more free time & energy.

[BookOfGreg]

I've made a new blank page on the Wiki here, but I do still think based on this checkbox that you should have permission already. I'll grant you write access anyway soon which should definitely sort that out.

[jtannas]

Finally got around to making a very basic logo. Anyone who is a designer PLEASE SEND HELP. In the meantime I hope this is OK.

Very slick looking - definitely a lot better than anything I could manage so let's go with it.
For a future revision, I think something that melds in the swagger logo would be nice. eg.

Sorry about all the JsPaint artifacting 😅

[BookOfGreg]

Aha, I was riffing off the OpenAPI logo with the connecting dots (example here) but yeah I wonder if the braces are more recognisable.
I'll ask an actual designer to take a look at it when I'm back at work, see if I can get some designer time donated.

[jtannas]

derp... I totally missed the OpenAPI connection. Carry on 🙃

[jtannas]

Do you have any thoughts on a good async communication tool? Team discussions in the org might do it but not used that before either.

Let's try moving this to Discussions and see how it works out - could help out people who want to contribute by having everything out in the open.

[jtannas]

@sergioisidoro @BookOfGreg I'm regretting putting this on discussions instead of something more chat-like.
The discussions section seems to be attracting more issue reports than actual discussions, making it harder to follow along.
Maybe Slack or Discord instead?

[romanblanco]

Unless this has been already settled on Discord, I'd like to propose to use a non-proprietary solution.

A room in https://libera.chat/ or https://matrix.to/#/#matrix:matrix.org could work.

Bridging Discord to IRC could also be an option to keep both options.

I guess the only question is if there would be interest.

[romanblanco]

#627

[BookOfGreg]

Just recording which ones are still TODO.

• Add in spellchecker (cspell?) for PRs

• Add https://github.com/marketplace/stale to help keep stale issues under control

• Are the issue templates working? I don't see anything come up when creating a new template. Assuming they're broken:

  • Add in a template chooser https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#configuring-the-template-chooser
  • Create issue forms (or wait until beta is complete?) https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms

• Set up a project wiki with an FAQ page;

  • Split the README into wiki pages

[BookOfGreg]

I don't like the stale bot, having been on the wrong side of a "stale" issue that is not stale more than once it's very frustrating for potential helpers in this community.

However I think while we're still getting the repo under control it makes sense to try reduce the scope of what we're trying to do, and remove the stale bot when we're a larger team more able to keep things clear, or when we're back to a stable state.

I reckon stale bot can be removed at some point, it would be nice to set some target around that. Maybe once we're back around ~3 months of issues?

[jtannas]

Agreed. I suggested it having seen it in other repos, but experiencing it 1st hand it I'm not a fan of keeping it long term.
I'm basically racing the bot to either preserve or to manually close issues after reviewing them.

[BookOfGreg]

Please don't feel like you're racing the bot! The best things that we can do are sustainable pace, and encourage more people to join us in the longer term.

[jtannas]

Down to under 100 issues! 🎉
But yeah... Good point about keeping a sustainable pace to avoid burnout. It's definitely something I'm keeping an eye on because <reasons />.

[romanblanco]

Split the README into wiki pages

My suggestion as a first step would be to keep these sections in the README.md:

• https://github.com/rswag/rswag#rswag
• https://github.com/rswag/rswag#getting-started
• https://github.com/rswag/rswag#compatibility

It gives a good first idea of what does the project do.

Anything that is below https://github.com/rswag/rswag#the-rspec-dsl or https://github.com/rswag/rswag#configuration--customization could be moved into Wiki pages, as it describes specifics.

For promoting the Wiki page and having easy access to the content, the README could contain table of Wiki content.

Will be happy to help (or just do) 🙂

[sergioisidoro]

I took a swing at the Template updates:
#496

PS: I did not self-merge because we did not agree on the reviewing process. Do we have one?

[BookOfGreg]

Thanks! 👍 They look good.

Do we have a reviewing process?
Currently no, since it's been me +1 for a long time there's been no real opportunity for placing in review gates as the risk is there would be no response for long periods of time.

It makes me wonder for other smaller gems if there isn't some kind of "review pool" of people who contribute who can review on other's gems.
In the meantime could you recommend a review policy? There have been a couple occasions lately while I was fixing the GH Actions deploy pipeline I was comitting to master which may want to be taken into account.

[sergioisidoro]

Awesome. I tested it and it works :)

In the meantime could you recommend a review policy?

I'm used to never merge a PR without a reviewer, so we could strive towards that :) It's easy to overlook our own mistakes. Of course that's not always possible, and it might slow down some things, so self-merging should be something we try to avoid, rather than written in stone.

In the future we could use the "code owners" feature to assign certain parts of the code to people who we know are most comfortable?

[BookOfGreg]

How about something along the lines of:

• Branch protection on master
  • No pushes directly to master
  • Status check required
  • 0 reviewer required, but write into the CONTRIBUTORS.md that we expect 1 reviewer unless repairing bugs intended to be released as a patch, or repairs to infrastructure (the GH Actions)

Not sure how useful Codeowners will be, think the whole thing will currently be me? 😅