Skip to content

Latest commit

 

History

History
423 lines (346 loc) · 57.9 KB

README.md

File metadata and controls

423 lines (346 loc) · 57.9 KB

Human Essentials

DPG Approved

Mission 💖

Human Essentials is an inventory management system built to address the needs of Diaper Banks as directly and explicitly as possible and adapted to meet the needs of other Essentials Banks. Essentials Banks maintain inventory, receive donations and other human essentials supplies (e.g. diapers, period supplies), and issue distributions to community partner organizations. Like any non-profit, they also need to perform reports on this data and have day-to-day operational information they need. This application aims to serve those needs and facilitate the general operations of the Diaper Banks (e.g., using barcode readers, scale weighing, inventory audits).

Impact 🌟

Human Essentials has over 200 registered banks across the United States at no cost to them. It is currently helping over 3 million children receive diapers and over 400k period supply recipients receive period supplies. Our team is in partnership with the National Diaper Bank Network (NDBN) and can be found in their annual conference that brings numerous of non-profit organizations that distribute essential products to people.

We are proud of our achievements up to date but there is much more to do! This is where you come in...

Ruby for Good

Human Essentials is one of many projects initiated and run by Ruby for Good. You can find out more about Ruby for Good at https://rubyforgood.org

Digital Public Good 🎉

The Digital Public Goods Alliance recognizes Human Essentials as a digital public good (DPG). This project supports the following Sustainable Development Goals:

  • SDG 1 - End poverty in all its forms everywhere
  • SDG 3 - Ensure healthy lives and promote well-being for all at all ages
  • SDG 10 - Reduce inequality within and among countries

Use as an Organization or Contribute as an Individual/Team to this Project:

Welcome Contributors! 👋

Thanks for checking us out! If you're new here, here are some things you should know:

  • Issues tagged "Help Wanted" are self-contained and great for new contributors
  • Pull Requests are reviewed within a week or so
  • Ensure your build passes (rubocop -a is often necessary) and addresses the issue requirements
  • This project relies entirely on volunteers, so please be patient with communication

Join us on slack 💬

You can sign up here and find us in #human-essentials. Many helpful members are available to answer your questions. Just ask, and someone will be there to help you!

Getting Started (Local Environment) 🛠️

  1. Install Ruby
    • Install the version specified in .ruby-version.
    • Visit the Install Ruby on Rails guide by GoRails for Ubuntu, Windows, and macOSX setup. ⚠️ Follow only the Installing Ruby step, as our project setup differs ⚠️ It is highly recommended you use a ruby version manager such as rbenv, asdf, or rvm.
    • Verify that your Ruby installation works by running ruby -v.
  2. Install Postgres
    • Follow one of these guides: MacOSX, Ubuntu.
      • Do you develop on Windows? We'd love to hear (and for you to submit a PR explaining) how you do it. 🙏🏻
    • Create a database.yml file on config/ directory with your database configurations. You can also copy the existing files called database.yml.example and .env.example and change the credentials.
  3. Clone the project and switch to its directory
  4. Run bin/setup
  5. Run bin/start and visit http://localhost:3000/ to see the human essentials page.
  6. Log in as a sample user with these default credentials (which also work for staging):
Super Users 🦸🏽‍♀️
  username: superadmin@example.com
  password: password!
Bank Users 🏦
  Organization Admin
     Email: org_admin1@example.com
  Password: password!

  User
  Email: user_1@example.com
  Password: password!
Partner Users 👥
  Verified Partner
  Email: verified@example.com
  Password: password!

  Invited Partner
  Email: invited@pawneehomeless.com
  Password: password!

  Unverified Partner
  Email: unverified@pawneepregnancy.com
  Password: password!

  Recertification Required Partner
  Email: recertification_required@example.com
  Password: password!

Getting Started (Codespaces - EXPERIMENTAL) 🛠️

Open in GitHub Codespaces

  1. Follow the link above or follow instructions to create a new Codespace.; You can use the web editor, or even better open the Codespace in VSCode
  2. Wait for the container to start. This will take a few (10-15) minutes since Ruby needs to be installed, the database needs to be created, and the bin/setup script needs to run
  3. Run bin/start and visit the URL that pops in VSCode up to see the human essentials page
  4. Login as a sample user with these default credentials (which also work for staging):

Troubleshooting 👷🏼‍♀️

Please let us know by opening up an issue! We have many new contributors come through and it is likely what you experienced will happen to them as well.

  • "My RBENV installation didn't work!" - The rbenv repository provides a rbenv-doctor script to verify the installation and check if a ruby version is installed

Contributing Guidelines 🤝

Please feel free to contribute! Priority will be given to pull requests that address outstanding issues and have appropriate test coverage. Focus on issues tagged with the next milestone for higher priority.

To contribute:

  • Identify an unassigned issue
  • Assign the issue to yourself to avoid duplicated efforts (or request assignment by adding a comment)
  • Fork the repo if you're not a contributor yet
  • Create a new branch for the issue using the format XXX-brief-description-of-feature, where XXX is the issue number
  • If you create a new model run bundle exec annotate from the root of the app
  • Create tests to validate that your work fixes the Issue (if you need help with this, please reach out!)
  • Commit locally using descriptive messages that indicate the affected parts of the app
  • Ensure all tests pass successfully; if any fail, fix the issues causing the failures
  • Make a final commit if tests needed fixing
  • Push up the branch
  • Create a pull request and indicate the addressed issue in the title

Squashing Commits

Consider the balance of "polluting the git log with commit messages" vs. "providing useful detail about the history of changes in the git log". If you have several smaller commits that serve a one purpose, you are encouraged to squash them into a single commit. There's no hard and fast rule here about this (for now), just use your best judgement. Please don't squash other people's commits. Everyone who contributes here deserves credit for their work! :)

Pull Request Merging

At this point, someone will work with you on doing a code review. If the automated tests gives 👍 to the PR merging, we can then do any additional (staging) testing as needed. Finally if all looks good the core team will merge your code in; if your feature branch was in this main repository, the branch will be deleted after the PR is merged. Deploys are currently done about once a week!

In-flight Pull Requests

Sometimes we want to get a PR up there and going so that other people can review it or provide feedback, but maybe it's incomplete. This is OK, but if you do it, please tag your PR with in-progress label so that we know not to review / merge it.

Becoming a Repo Contributor

Users that are frequent contributors and are involved in discussion (join the slack channel! :)) may be given direct Contributor access to the Repo so they can submit Pull Requests directly instead of Forking first.

Stay Scoped

Try to keep your PRs limited to one particular issue, and don't make changes that are out of scope for that issue. If you notice something that needs attention but is out of scope, please create a new issue.

Debugging

If starting server directly, via rail s or rail console, or built-in debugger in RubyMine, then you can use binding.pry to debug. Drop the pry where you want the execution to pause.

If starting via Procfile with bin/start, then drop a binding.remote_pry into the line where you want execution to pause at. Then run pry-remote in the terminal to connect to it. https://github.com/Mon-Ouie/pry-remote

Testing 🧪

Writing Tests/Specs

  • Run all the tests with bundle exec rspec
  • Run a single test with bundle exec rspec {path_to_test_name}_spec.rb

Make sure all tests run clean & green before submitting a Pull Request. If you are inexperienced in writing tests or get stuck on one, please reach out for help :). You probably don't need to write new tests when simple re-stylings are done (ie. the page may look slightly different but the Test suite is unaffected by those changes).

Tip: If you need to skip a failing test, place pending("Reason you are skipping the test") into the it block rather than skipping with xit. This will allow rspec to deliver the error message without causing the test suite to fail.

  it "works!" do
    pending("Need to implement this")
    expect(my_code).to be_valid
  end

Writing Browser/System/Feature Specs

If you need to see a browser/system spec run in the browser, you can use the following env variable:

NOT_HEADLESS=true bundle exec rspec

We've added magic_test which makes creating browser specs much easier. It allows you to record actions on the browser running the specs and easily paste them into the spec. You can do this by adding magic_test within your system spec:

 it "does some browser stuff" do
   magic_test
 end

and run the spec using this command: MAGIC_TEST=1 NOT_HEADLESS=true bundle exec rspec <path_to_spec>

See videos of it in action here

Deployment Process 🚀

The human-essentials & partner application should ideally be deployed on a weekly or bi-weekly schedule depending on the merged updates in the main branch. This is the process we take to deploy updates from our main branch to our servers.

Requirements

  • SSH access to our servers (usually granted to core maintainers)
  • Login credentials to our Mailchimp account

Tag & Release

  1. Push a tag with the appropriate semantic versioning. Refer to the releases for the correct versioning. For example, if the last release was 2.1.0 and you're making a hotfix, use 2.1.1

    git tag x.y.z
    git push --tags
  2. Publish a release associated to that tag pushed up in the previous step here. Include details about the release's updates (we use this to notify our stakeholders on updates via email).

Running delayed jobs

Run delayed jobs locally with the rake jobs:work command. This is necessary to view any emails in your browser. Alternatively, you can run a specific delayed job by opening a Rails console and doing something like:

Delayed::Job.last.invoke_job

You can replace the last query with any other query (e.g. Delayed::Job.find(123)).

Additional Notes

  • Only commit the schema.rb only if you have committed anything that would change the DB schema (i.e. a migration).

Acknowledgements

Thanks to Rachel (from PDX Diaperbank) for all of her insight, support, and assistance with this application, and Sarah ( http://www.sarahkasiske.com/ ) for her wonderful design and CSS work at Ruby For Good '17!

License

FOSSA Status

✨ Contributors ✨

Thanks goes to these wonderful people (emoji key):

Edwin Mak
Edwin Mak

💻 📆 🚇 🤔 💬 🛡️
Sean Marcia
Sean Marcia

💻 💼 💵 🔍 📋
Aaron H
Aaron H

📆 💻
Dmitry
Dmitry

💻
Adam Bachman
Adam Bachman

💻
JC Avena
JC Avena

💻
mdworken
mdworken

💻 📆
Marius Pop
Marius Pop

💻
Elayne
Elayne

💻
Amy Detwiler
Amy Detwiler

💻
Gia
Gia

💻
Amina Adewusi
Amina Adewusi

💻
albertchae
albertchae

💻 🤔
Keith Walters
Keith Walters

💻
Chase Southard
Chase Southard

💻
Brock Wilcox
Brock Wilcox

💻
danquill
danquill

💻
Keith Bennett
Keith Bennett

💻
Benjamin Reynolds
Benjamin Reynolds

💻
jtu0
jtu0

💻
Juarez Lustosa
Juarez Lustosa

💻
Julien A.
Julien A.

💻
Emerson Manabu Araki
Emerson Manabu Araki

💻
Ben Klang
Ben Klang

💻
karolina
karolina

💻
Josh Cano
Josh Cano

💻
Julian Macmang
Julian Macmang

💻
Philip DeFraties
Philip DeFraties

💻
GabrielRMuller
GabrielRMuller

💻
Lucas Hiago
Lucas Hiago

💻
Lanya Butler
Lanya Butler

💻
Eduardo Moreira
Eduardo Moreira

💻
Alicia Barrett
Alicia Barrett

💻
Bob Forcha
Bob Forcha

💻
William Murphy
William Murphy

💻
Kate Donaldson
Kate Donaldson

💻
Matthew Russell Dodds
Matthew Russell Dodds

💻
Allison McMillan
Allison McMillan

💻
Ashley Jean
Ashley Jean

💻
Eduardo Alencar
Eduardo Alencar

💻
Thomas Hart
Thomas Hart

💻
Bart Agapinan
Bart Agapinan

💻
Monique
Monique

💻
Valerie Woolard
Valerie Woolard

💻
zak-kay
zak-kay

💻
Jason LaHatte
Jason LaHatte

💻
Dave Tapley
Dave Tapley

💻
Meghan
Meghan

💻
Andy Thackray
Andy Thackray

💻
Felipe Lovato Flores
Felipe Lovato Flores

💻
Marcel Kooi
Marcel Kooi

💻
Lee Sharma
Lee Sharma

💻
Scott Steele
Scott Steele

💻 🤔
Sam Weerasinghe
Sam Weerasinghe

💻
Gerald Abrencillo
Gerald Abrencillo

💻
Rodolfo Santos
Rodolfo Santos

💻
Gabriel Baldão
Gabriel Baldão

💻
Melanie White
Melanie White

💻
Melissa Miller
Melissa Miller

💻
Marc Heiligers
Marc Heiligers

💻
Joe Hunt
Joe Hunt

💻
Meg Gutshall
Meg Gutshall

💻
Andrew H Schwartz
Andrew H Schwartz

💻
Joseph Glass
Joseph Glass

💻
Reese Williams
Reese Williams

💻
Santiago Perez
Santiago Perez

💻
Sirius Dely
Sirius Dely

💻
Heather Herrington
Heather Herrington

💻
Moacir Guedes
Moacir Guedes

💻
CraigJZ
CraigJZ

💻
Semih Arslanoğlu
Semih Arslanoğlu

💻
Mauricio de Lima
Mauricio de Lima

💻
David Curtis
David Curtis

💻
Natalia Galán
Natalia Galán

💻
Anderson Fernandes
Anderson Fernandes

💻
Gabriel Belgamo
Gabriel Belgamo

💻
Jorge David C.T Junior
Jorge David C.T Junior

💻
Seth Lieberman
Seth Lieberman

💻
Jorge Oliveira Santos
Jorge Oliveira Santos

💻
Drinks
Drinks

💻
Bruno Castro
Bruno Castro

💻
Carlos Palhares
Carlos Palhares

💻
Clifton McIntosh
Clifton McIntosh

💻
Daniel Beigelman
Daniel Beigelman

💻
Meg Viar
Meg Viar

💻
Svetlana Vileshina
Svetlana Vileshina

💻
Ben Reed
Ben Reed

💻
Emily Giurleo
Emily Giurleo

💻
Alem Getu
Alem Getu

💻
Dejan Bjeloglav
Dejan Bjeloglav

💻
Cassiano Blonski Sampaio
Cassiano Blonski Sampaio

💻
Greg
Greg

💻
finn
finn

💻
Jayson Mandani
Jayson Mandani

💻
Stanley Liu
Stanley Liu

💻
Curtis Bartell
Curtis Bartell

💻
Libby Rodriguez
Libby Rodriguez

💻
joshuacgraves
joshuacgraves

💬 📆
Himanshu
Himanshu

💻
Mohamed Hegab
Mohamed Hegab

💻
Alejandro AR
Alejandro AR

💻
hatsu
hatsu

💻
Matt Glover
Matt Glover

💻
js-sapphire
js-sapphire

💻
lasitha
lasitha

💻
Patrick McClernan
Patrick McClernan

💻
Marc Bellingrath
Marc Bellingrath

💻
Daniel Orner
Daniel Orner

💻
Bob Mazanec
Bob Mazanec

💻
Mark Yen
Mark Yen

💻
Rachael Wright-Munn
Rachael Wright-Munn

💻
Ítalo Matos
Ítalo Matos

💻
Alvaro Sanchez Diaz
Alvaro Sanchez Diaz

💻
mbrundige
mbrundige

💻
Robert Greene
Robert Greene

💻

This project follows the all-contributors specification. Contributions of any kind welcome!