Developer experience audit from @mntnr

[RichardLitt]

👋 Hey there! This is the developer experience audit from @mntnr for this repository. I've added in my thoughts below, in the form of a checklist. Looking forward to seeing what you think; let's see if we can resolve all of the open issues and make this repository shine ✨ 💖 ✨

Repository Review: probot/template

Template for new Probot apps

For notes on anything crossed out, look below. Note: I use [~] to mean that I have proposed a fix in a PR. I know it doesn't render properly in Markdown, but it works pretty well otherwise for that purpose. If I think that something is fine, even if it isn't valid according to this checklist, I've checked it off and included a note.

Reviewing the Repository Docs

• Is there a README?
  • Does it follow standard-readme? Good enough.
  • Is it spellchecked?
• Is there a Code of Conduct, such as the Contributor Covenant?
  • Is it mentioned in the Contribute section of the README? (Note: this isn't needed if you mention it in your CONTRIBUTE.md and it is in this repository.)
  • Does it reference an email address for violations?
• Is there a LICENSE file?
  • Is this matched in the package.json?
  • Is the year correct?
• Is there a .github or docs folder? Might be worth adding this?
  • Is there an ISSUE_TEMPLATE.md?
  • Is there a PULL_REQUEST_TEMPLATE.md?
• Is there a CONTRIBUTING.md file?
  • Does it mention how to make a PR?
  • Does it mention what sort of issues you'd like?
  • Does it mention a good first issue label as a starting point? Might be good to add these?)
  • Does it mention triaging and bug reports as good starting points?
  • Does it point to a community chat program, like Slack or Gitter?
  • Does it encourage conversations in issues before opening huge PRs?
  • Does it specify where to ask questions on process?
  • Does it explain labels used in the issues?
• Is there a CHANGELOG? Assuming they use releases.
  • If there isn't, are notes included in the project's releases?
• Does this pass alex adequately? Run alex *.md.
• Does the repository name itself pass on http://wordsafety.com?

Process

• Can I install easily? Is there a way of copying this easily? For instance, adding it as a Yeoman app?
• Can I use this easily?

Issues and Pull Requests

• Are there an acceptable amount of pull requests?
• Are there an acceptable amount of issues?
• Are an acceptable amount of issues less than six months old?
• Are there useful issue labels?
• Are the labels being used?

Bots

• Are the bots listed in the Contribute or Readme files so that users can expect to interact with them? I added an example, commented out bot section.

TODO

• It would be great to have a document in this repo - a second README - explaining how to best use the template. Is copying the best way, for instance? Or is there a Yeoman app? Is there a bot to set it up? That sort of thing.
• Sometimes {{}} are used, and sometimes triple brackets. I'm not sure why.
• Consider adding ISSUE_TEMPLATE.md and PULL_REQUEST_TEMPLATE.md files to this repository. Might be a good idea to start things off well.

Contribute back?

This checklist is open source! If you have suggestions or think it could be better, contribute back on mntnr/audit-templates.

Thank you!

[hiimbex]

Can I install easily? Is there a way of copying this easily? For instance, adding it as a Yeoman app?
Can I use this easily?

YES! create-probot-app, found in the docs here: https://probot.github.io/docs/development/#generating-a-new-app

If I'm being honest, I don't expect many people to land in this repository, but because the create-probot-app uses this repo as a literal template, any files we add to this template will be files like someones app will automatically generate right now. (I can tell you get that based on the pr :) )

But if you think there's a better way to express those links to create-probot-app, I'd be open to suggestions about that!

Probot

Developing an app

GitHub Apps to automate and improve your workflow

[RichardLitt]

If I'm being honest, I don't expect many people to land in this repository, but because the create-probot-app uses this repo as a literal template, any files we add to this template will be files like someones app will automatically generate right now. (I can tell you get that based on the pr :) )

I think we should probably add a file called REMOVEME.md or INSTRUCTIONS.md, or just edit the README to have a section saying ## Remove this after cloning that explains how to copy this app using create-probot-app. It wasn't intuitive to me how to use this repo coming from GitHub, although you're right that that may not be the most likely entry point. But where this is accessed from shouldn't influence how it can be understood; this repository should probably self-describe, at least a little bit.

Why don't I just add a section to the README with that information?

[RichardLitt]

I think my only remaining points which matter are in the TODO section. @bkeepers Want to verify that, and if possible, we can close this up?