Skip to content

Commit

Permalink
Readme updates (#3766)
Browse files Browse the repository at this point in the history 
* Mostly whitespace cleanup with some minor rewording

* Remove notes on emailing users and work-arounds

Contributors won't need to email users directly and these instructions
are outdated anyway. The work-arounds for schema notes is simplified
too.
  • Loading branch information
@awwaiid
awwaiid committed Jul 23, 2023
1 parent 3e6254e commit 3a0ee9e
Showing 1 changed file with 55 additions and 87 deletions.
142 changes: 55 additions & 87 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Human Essentials
# Human Essentials
<p align="center">
<a href="https://app.digitalpublicgoods.net/a/10622">
<img src="https://user-images.githubusercontent.com/667909/181150972-e59a77ab-b657-4893-aef9-d3df1384a506.png" alt="DPG Approved" height="40">
Expand Down Expand Up @@ -29,7 +29,6 @@
<a href="https://github.com/rubyforgood/human-essentials/" alt="Watchers"><img src="https://img.shields.io/github/watchers/rubyforgood/human-essentials?style=social" /></a>
</p>


## Mission 💖

Human Essentials is an inventory management system built to address the needs of [Diaper Banks](https://nationaldiaperbanknetwork.org/diaper-need/) 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).
Expand All @@ -44,100 +43,89 @@ We are proud of our achievements up to date but there is much more to do! This i

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](https://digitalpublicgoods.net/registry/) recognizes Human Essentials as a digital public good (DPG). This project supports the following Sustainable Development Goals:
* [SDG 1](https://sdgs.un.org/goals/goal1) - End poverty in all its forms everywhere
* [SDG 3](https://sdgs.un.org/goals/goal3) - Ensure healthy lives and promote well-being for all at all ages
* [SDG 10](https://sdgs.un.org/goals/goal10) - Reduce inequality within and among countries

## Uses
Use as an Organization or Contribute as an Individual/Team to this Project:
- [NGO Adoption Info](ngo.md) - information about how to use this DPG
- [Skills Based Volunteering Info](sbv.md) - information about how to volunteer

</br>

# 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
- 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
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](https://rubyforgood.slack.com/join/shared_invite/zt-1kfeimohe-KL~~~6Lkof7G94_7Ojd_Hw#/shared-invite/email) 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 🛠️


1. Install Ruby
- Install the version specified in [`.ruby-version`](.ruby-version).
- Visit the [Install Ruby on Rails](https://gorails.com/setup/osx/12-monterey) 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](https://github.com/rbenv/rbenv), [asdf](https://asdf-vm.com/), or [rvm](https://rvm.io/).
1. Install Ruby
- Install the version specified in [`.ruby-version`](.ruby-version).
- Visit the [Install Ruby on Rails](https://gorails.com/setup/osx/12-monterey) 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](https://github.com/rbenv/rbenv), [asdf](https://asdf-vm.com/), or [rvm](https://rvm.io/).
- Verify that your Ruby installation works by running `ruby -v`.
2. Install Postgres
- Follow one of these guides: [MacOSX](https://www.digitalocean.com/community/tutorials/how-to-use-postgresql-with-your-ruby-on-rails-application-on-macos), [Ubuntu](https://www.digitalocean.com/community/tutorials/how-to-use-postgresql-with-your-ruby-on-rails-application-on-ubuntu-18-04).
- Do you develop on Windows? We'd love to hear (and for you to submit a PR explaining) how you do it. 🙏🏻
- 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`](config/database.yml.example) and [`.env.example`](.env.example) and change the credentials.
3. Run `bin/setup`
4. Run `bin/start` and visit http://localhost:3000/ to see the human essentials page.
5. Login as a sample user with these default credentials:
5. Login as a sample user with these default credentials (which also work for [staging](https://staging.humanessentials.app/)):

<details>
<summary> Super Users 🦸🏽‍♀️ </summary>
<br>

```
<details>
<summary> Super Users 🦸🏽‍♀️ </summary>

```
username: superadmin@example.com
password: password!
```
```
</details>

<details>
<summary> Bank Users 🏦 </summary>

</details>
</br>
<details>
<summary> Bank Users 🏦 </summary>
<br>

```bash
```
Organization Admin
Email: org_admin1@example.com
Password: password!
Email: org_admin1@example.com
Password: password!
User
Email: user_1@example.com
Password: password!
```
</details>
</br>

<details>
<summary> Partner Users 👥 </summary>
<br>

```bash
Email: user_1@example.com
Password: password!
```
</details>

<details>
<summary> Partner Users 👥 </summary>

```
Verified Partner
Email: verified@example.com
Password: password!
Email: verified@example.com
Password: password!
Invited Partner
Email: invited@pawneehomeless.com
Password: password!
Email: invited@pawneehomeless.com
Password: password!
Unverified Partner
Email: unverified@pawneepregnancy.com
Password: password!
Recertification Required Partner
Email: recertification_required@example.com
Password: password!
```
Email: unverified@pawneepregnancy.com
Password: password!
</details>
Recertification Required Partner
Email: recertification_required@example.com
Password: password!
```
</details>

## 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](https://github.com/rbenv/rbenv-installer#rbenv-doctor) to verify the installation and check if a ruby version is installed
Expand All @@ -147,23 +135,25 @@ Please let us know by opening up an issue! We have many new contributors come th
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
* 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
* 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 provide proof that your work fixes the Issue (if you need help with this, please reach out!)
* 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 that point, someone will work with you on doing a code review. If TravisCI gives :+1: to the PR merging, we can then merge your code in; if your feature branch was in this main repository, the branch will be deleted after the PR is merged.

At this point, someone will work with you on doing a code review. If the automated tests gives :+1: 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

Expand Down Expand Up @@ -238,37 +228,16 @@ Delayed::Job.last.invoke_job
You can replace the `last` query with any other query (e.g. `Delayed::Job.find(123)`).
### Send Update Email To Human Essential Users
To notify stakeholders about the deployment and updates via email, follow these steps:

1. Fetch all the users' emails from our human essentials production database
```ruby
cap production rails:console
emails = User.all.pluck(:email)
puts "Email Address\n" + emails.join("\n") # Copy this output
```
2. Use the copied list of emails to send an update audience via [Mailchimp](https://mailchimp.com/). Go to Audience > Manage Audience > Import Contacts and select "Copy and paste" option. Then paste the email list from the previous step.
3. Draft and send the email with updates.
### Additional Notes
- The generated `schema.rb` file may include or omit `id: :serial` for `create table`, and `null: false` for `t.datetime`. According to Aaron, this can safely be ignored, and it is probably best to commit the schema.rb only if you have committed anything that would change the DB schema (i.e. a migration).
- If you have trouble relating to SSL libraries installing Ruby using `rvm` or `rbenv` on a Mac, you may need to add a command line option to specify the location of the SSL libraries. Assuming you are using `brew`, this will probably result in a command looking something like:
```bash
rvm install 2.6.4 --with-openssl-dir='brew --prefix openssl'
```
- 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](https://app.fossa.com/api/projects/git%2Bgit.luolix.top%2Frubyforgood%2Fdiaper.svg?type=large)](https://app.fossa.com/projects/git%2Bgit.luolix.top%2Frubyforgood%2Fdiaper?ref=badge_large)


# ✨ Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Expand Down Expand Up @@ -437,4 +406,3 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!


0 comments on commit 3a0ee9e

Please sign in to comment.