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).
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...
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
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:
- NGO Adoption Info - information about how to use this DPG
- Skills Based Volunteering Info - information about how to volunteer
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 -ais often necessary) and addresses the issue requirements - This project relies entirely on volunteers, so please be patient with communication
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!
- 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.
- Install the version specified in
- 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.ymlfile onconfig/directory with your database configurations. You can also copy the existing files calleddatabase.yml.exampleand.env.exampleand change the credentials.
- Follow one of these guides: MacOSX, Ubuntu.
- Clone the project and switch to its directory
- Run
bin/setup - Run
bin/startand visit http://localhost:3000/ to see the human essentials page. - 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!
- 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
- 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/setupscript needs to run - Run
bin/startand visit the URL that pops in VSCode up to see the human essentials page - Login as a sample user with these default credentials (which also work for staging):
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
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, whereXXXis the issue number - If you create a new model run
bundle exec annotatefrom 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
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! :)
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!
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.
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.
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.
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
- 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
endIf 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
endand 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
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.
- SSH access to our servers (usually granted to core maintainers)
- Login credentials to our Mailchimp account
-
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.0and you're making a hotfix, use2.1.1git tag x.y.z git push --tags
-
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).
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_jobYou can replace the last query with any other query (e.g. Delayed::Job.find(123)).
- Only commit the schema.rb only if you have committed anything that would change the DB schema (i.e. a migration).
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!
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!