Coder Social home page Coder Social logo

split-sinatra-example's People

Contributors

andrehjr avatar andrew avatar dependabot-preview[bot] avatar dependabot-support avatar dependabot[bot] avatar phoet avatar richardlitt avatar strand avatar

Stargazers

avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar avatar

Forkers

gsonbuchner phoet strand apyrros mntnr

split-sinatra-example's Issues

Documentation edits

👋 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: splitrb/split-sinatra-example

📖 Example of using split in a sinatra app

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? More or less
    • Is it spellchecked? See TODO section below for minor issues.
  • 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?
    • Does it reference a second email address? See TODO section.
  • Is there a LICENSE file?
    • [~] Is the year correct? Year is 2013.
  • Is there a .github or docs folder?
    • Is there an ISSUE_TEMPLATE.md?
    • Is there a PULL_REQUEST_TEMPLATE.md?
  • [~] Is there a CONTRIBUTING.md file? See TODO section below for recommendation.
    • [~] 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?
    • 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?
    • If there isn't, are notes included in the project's releases?
  • Does this pass alex adequately? Run alex *.md. 5 warnings, all false positives.
  • Does the repository name itself pass on http://wordsafety.com?

Process

  • Can I install easily? There were some hiccups; see TODO section for recommendations.
  • Can I use this easily?

Issues and Pull Requests

  • Are there an acceptable amount of pull requests? 0 open, 2 closed at time of audit; seems reasonable for a project like this.
  • Are there an acceptable amount of issues? 2 open, 34 closed at time of audit; seems reasonable for a project like this.
  • Are an acceptable amount of issues less than six months old? 2 open, 3 closed at time of audit; seems reasonable for a project like this.
  • Are there useful issue labels?
  • Are the labels being used?
  • Is there a good for beginners or good first issue label?
  • Is there a waiting on contributor label?

Bots

Note: Neither of these are necessary, but they can help with some things. Check out https://probot.github.io/ for some tools.

  • Are there bots enabled?
  • Are the bots listed in the Contribute or Readme files so that users can expect to interact with them? N/A.

Metadata

  • Is there a description on GitHub?
    • Does the description match the README? No, but the solution is to fix the readme (and correct spelling issue in both places); noted in TODO below.
  • Are the topics useful? No topics; this is noted in the TODO below.
  • Is there a website? N/A.
    • Does the website match the project? N/A.

TODO

  • [~] Make changes so that the README conforms to the standard-readme spec; the following criteria aren't met:
    • The short description does not match the GitHub repo description (see notes on Short Description field in standard-readme for suggestions on setting this up).
    • There's no "Install" section (it would be preferable to have a single Install section, and for it to include Requirements and Setup sections as subsections of that, as is the case with the split repo).
  • [~] "Spelling" issues in readme, etc.:
    • The word "sinatra" should be capitalized in both the GH description and the readme title.
    • "a/b" should be "A/B"
  • [~] As this is documentation of a particular way to use split, and is intended to be a very basic example, this repo would probably be well-served by having a short, custom CONTRIBUTE.md. I've started it, but this may benefit from better content.
  • [~] The lack of an "Install" section makes it confusing as to how to fully set up the example app. If there is no need to install anything, that would be helpful to know. I learned a little by looking at the config.ru file, and maybe this is a non-issue for the target audience, but to someone with no experience with split, this is confusing. (FTR, once I got it running, it was very cool to see the split dashboard. 😃)
    • I was starting with the repo already cloned, so I'm guessing that may be a required step?
    • In the end, I got it up and running by running the commands in two separate terminal windows, because spinning up the Redis server didn't give me a prompt back, so you can't actually run the commands as currently written. Perhaps the command should be redis-server & (I think that backgrounds the process), or you should mention to fire up a second command shell to run the second command.
    • To get the second command to work, I had to do bundle exec rackup config.ru because, when I first ran the second command, I got back "You have already activated rack 2.0.5, but your Gemfile requires rack 2.0.4. Prepending bundle exec to your command may solve this. (Gem::LoadError)". (That command also didn't give back control of the terminal, so maybe they should both be run backgrounded?) (Also, I didn't test this, but I assume the first command can be run from any directory, while the second must be run (at least as written) from the repo's main directory, since that's where config.ru lives.)
  • I would recommend adding topics to the repo below the GH description.

Generic

  • I would add a maintainers section, to make it clear who is on the maintainers team. This helps set expectations and clarifies for the users who they can talk to.
  • Add a link to your Slack or Gitter! You want to engage with users there. The main split repo points to your Google Groups; this works unless you have a different collaboration medium you prefer (but recommend adding to Contribute section of readme and/or CONTRIBUTE.md).
  • Consider adding a secondary email to the Code of Conduct as a contact - someone may have an issue with you but not want to tell you directly. I know, this idea may be awkward. But you will give them an option in case they do have an option, and this may be good for the overall health of the project. I'd be happy to add my email if it helps.
  • This audit does not cover license dependency. For that, I suggest using either licensee or an external tool like Fossa. Let me know if you want more help here.

Issues

  • Consider adding available labels as well as good first issue. These can be used to signal that you're looking for community involvement for issues. They can also be configured to display on http://up-for-grabs.net. This will help more people interact with your code, and lead to small, iterative work done by others. It may take some time to set up initially - properly scoping issues for newcomers takes some time - but the payback should be worth it.
  • I label pull requests where I am waiting on the Contributor to respond waiting on contributor. This helps alleviate pressure on you to close them.

Contribute back?

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

As well - note that you don't need to tick every box. If you have anything you'd like to talk about, I'm here; otherwise, I would suggest either pulling out tasks into a comment before, or into other issues, and then closing the issue when you feel you've adequately done everything. If you want help here, let me know.

Thank you!

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.