Skip to content

Commit

Permalink
README update (#9488)
Browse files Browse the repository at this point in the history 
* README update

I hope you don't mind, but I took the liberty to make some changes to wording that would make things more succinct and clearer. I also made certain items links because the way they were written kind of positioned them in a way that makes more sense to link them. Please let me know if there are any problems and I'll be sure to fix them. Thank you for this opportunity. I went through the docs and you guys are doing awesome things.

* fix(docs): quoted and made word singular
  • Loading branch information
@OlaoluwaM
OlaoluwaM authored Apr 15, 2021
1 parent e646cfd commit 0ed4fc8
Showing 1 changed file with 27 additions and 29 deletions.
56 changes: 27 additions & 29 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,13 @@ PublicLab.org
[![Newcomers welcome](https://img.shields.io/badge/newcomers-welcome-pink.svg)](https://code.publiclab.org) [![GitHub license](https://img.shields.io/github/license/publiclab/plots2?logo=gpl)](https://github.com/publiclab/plots2/blob/main/LICENSE)
[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/publiclab/plots2/)

The content management system for the Public Lab research community, the `plots2` web application is a combination of a group research blog of what we call "research notes" and a wiki. Read more about the [data model here](https://github.com/publiclab/plots2/blob/main/doc/DATA_MODEL.md).
The content management system for the Public Lab research community, the `plots2` web application is a combination of a group research blog -what we call "research notes"-and a wiki. Read more about the [data model here](https://github.com/publiclab/plots2/blob/main/doc/DATA_MODEL.md).

Begin running (and contributing to) this codebase immediately with [GitPod](https://gitpod.io):

[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/publiclab/plots2)

It showcases a variety of features that help the Public Lab community collaborate on environmental technology design and documentation, as well as community organizing. Originally a Drupal site, it was rewritten in 2012 in Ruby on Rails and has since extended but [not yet entirely replaced](https://github.com/publiclab/plots2/issues/956) the legacy Drupal data model and database design. We ❤️ Open Source and actively participate in various OSS programs such as [Google Summer of Code(GSoC)](https://publiclab.org/wiki/gsoc), Rails Girls Summer of Code (RGSoC), Outreachy and Google Code-In (GCI).
It showcases a variety of features that help the Public Lab community collaborate on environmental technology, design, documentation, and community organizing. Originally a Drupal site, it was rewritten in 2012 with Ruby on Rails and has since extended but [not yet entirely replaced](https://github.com/publiclab/plots2/issues/956) the legacy Drupal data model and database design. We ❤️ Open Source and actively participate in various OSS programs such as [Google Summer of Code(GSoC)](https://publiclab.org/wiki/gsoc), Rails Girls Summer of Code (RGSoC), Outreachy, and Google Code-In (GCI).
Some key features include:

* A [Q&A portal](https://publiclab.org/questions) for peer-based problem solving
Expand All @@ -29,12 +29,11 @@ Some key features include:
* A user dashboard [presenting recent activity](https://publiclab.org/dashboard)
* A privacy-sensitive, Leaflet-based [location tagging system](https://github.com/publiclab/leaflet-blurred-location/) and [community map](https://publiclab.org/people)


## Roadmap

We are developing a draft Roadmap for `plots2` and our broader Public Lab code projects; [read more and comment here](https://publiclab.org/notes/warren/05-22-2019/draft-of-a-public-lab-software-roadmap-comments-welcome).

A full description of features, audience, inter-relationships, and goals of Public Lab software projects can be found here: https://publiclab.org/software-overview
A full description of the features, audiences, inter-relationships, and goals of Public Lab software projects can be found here: https://publiclab.org/software-overview

## Table of Contents

Expand All @@ -58,19 +57,17 @@ A full description of features, audience, inter-relationships, and goals of Publ
16. [Security](#security)
17. [Developers](#developers)
18. [First Time?](#first-time)


****

## What makes this project different

The people who create our platform make very different design and technology decisions from other projects, and this stems from our deep belief that, to see a change in the world, we must build and maintain systems that **reflect our values and principles.**
The people who create our platform make very different design and technology decisions from other projects. This stems from our deep belief that, to see a change in the world, we must build and maintain systems that **reflect our values and principles.**

From design to system architecture to basic vocabulary and communication patterns, our systems have grown organically since 2010 to support a powerful, diverse, and cooperative network of people capable of taking on environmental problems that affect communities around the world. The platform we have built together speaks to this shared history in many ways, big and small. It reflects input from people facing serious health issues, on-the-ground organizers, policy specialists, hardware hackers, educators, and civil servants.
From design to system architecture to basic vocabulary and communication patterns, our systems have grown organically since 2010 to support a powerful, diverse, and cooperative network of people capable of taking on environmental problems that affect communities globally. The platform we have built together speaks to this shared history in many ways, big and small. It reflects input from people facing serious health issues, on-the-ground organizers, policy specialists, hardware hackers, educators, and civil servants.

This broad community, and the Public Lab team have facilitated a space where we can discuss, break down, construct, prototype, and critique real-world projects. Together we have shaped a platform that incorporates familiar pieces, but ultimately looks and feels quite different from anywhere else on the internet. Our platform continues to grow and be refined, but it also reflects a commitment to listening to one another, to mutual respect and support, to an awareness of the barriers and challenges presented by gaps in expertise and knowledge, and a sensitivity to the inequalities and power imbalances perpetuated by many mainstream modes of knowledge production and technological and scientific development.
This broad community and the Public Lab team have facilitated a space where we can discuss, break down, construct, prototype, and critique real-world projects. Together we have shaped a platform that incorporates familiar pieces but ultimately looks and feels quite different from anything else on the internet. Despite the growth of our platform, it remains committed to hearing the voices of others, mutual respect and support, an awareness of the barriers and challenges presented by gaps in expertise and knowledge, and a sensitivity to the inequalities and power imbalances perpetuated by many mainstream modes of knowledge production and technological and scientific development.

Our mutual aims of democratizing inexpensive and accessible do-it-yourself techniques has allowed us to create a collaborative network of practitioners who actively re-imagine the human relationship with the environment. Our goals are supported and facilitated by a system which questions and even challenges how collaborative work can happen.
Our mutual aim to democratize inexpensive and accessible do-it-yourself techniques has allowed us to create a collaborative network of practitioners who actively re-imagine the human relationship with the environment. Our goals are supported and facilitated by a system which questions and even challenges how collaborative work can happen.

## Data Model

Expand Down Expand Up @@ -106,20 +103,20 @@ For installation, prerequisites include sqlite3 and rvm. [Click here for a compl
* Install gems with `bundle install` from the rails root folder.
6. Run `cp db/schema.rb.example db/schema.rb` to make a copy of `db/schema.rb.example` in `db/schema.rb`.
7. You could choose to use mysql2 or sqlite3 as your database
* If mysql2, run `cp config/database.yml.mysql.example config/database.yml` to make a copy of `config/database.yml.mysql.example` in `config/database.yml`
* If mysql2, run `cp config/database.yml.mysql.example config/database.yml` to make a copy of `config/database.yml.mysql.example` in `config/database.yml`
* If sqlite3, run `cp config/database.yml.sqlite.example config/database.yml` to make a copy of `config/database.yml.sqlite.example` in `config/database.yml`.
_kindly note if you choose to use sqlite some tests may fail. The project was setup initially to use mysql and some tests are tailored for mysql db. No need for alarm, we are working to fix these and this will not interfere with your development process_
8. Run `rake db:setup` to set up the database
9. Install static assets (like external javascript libraries, fonts) with `yarn install`
10. Setup React & webpacker by running `rails webpacker:install && rails webpacker:install:react && rails generate react:install`(for local SSL work, see [SSL](#ssl-in-development) below)
* If you get any prompt to overwrite files in this step please choose no. The prompt will be something like _"Overwrite /home/plots2/config/webpacker.yml? (enter "h" for help) [Ynaqdhm]"_ :- type "n" and enter.
10. Setup React & webpacker by running `rails webpacker:install && rails webpacker:install:react && rails generate react:install`(for local SSL work, see [SSL](#ssl-in-development) below)
* If you get any prompt to overwrite files in this step please choose no. The prompt will be something like _"Overwrite /home/plots2/config/webpacker.yml? (enter "h" for help) [Ynaqdhm]"_ :- type "n" and enter.
11. Start the server with `passenger start` and navigate to `http://localhost:3000/` on your browser.
12. Wheeeee! You're up and running! Log in with test usernames "user", "moderator", or "admin", and password "password".
13. Run `rails test` to confirm that your install is working properly. You can also run `rails test:system` for system tests. (_Note: if you chose sqlite as your database, some tests may fail; Please ignore these, we are working to fix this. If your server starts correctly, you are all set_)

### Windows Installation

We recommend you either work in a virtual environment, or on a dual booted system to avoid dependencies issues and also Unix system works smoother with Ruby and Rails. This will not only benefit you now for plots2, but also in the future while working on other Ruby projects, a Linux or Mac based OS will make your development so much smoother.
We recommend you either work in a virtual environment, or on a dual booted system to avoid dependencies issues as Unix systems tend to work smoother with Ruby and Rails. This will not only benefit you now for plots2, but also in the future while working on other Ruby projects, a Linux or Mac based OS will make your development much easier.
1. [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) (recommended)
2. [Dual Booting](https://www.tecmint.com/install-ubuntu-alongside-with-windows-dual-boot/amp/), [option2](https://askubuntu.com/questions/1031993/how-to-install-ubuntu-18-04-alongside-windows-10), [video guide](https://www.youtube.com/watch?v=qNeJvujdB-0&fbclid=IwAR0APhs89jlNR_ENKbSwrp6TI6P-wxlx-a0My9XBvPNAfwtADZaAXqcKtP4)
3. [Setting up a Linux virtual env](https://itsfoss.com/install-linux-in-virtualbox/)
Expand All @@ -138,7 +135,7 @@ Public Lab uses Redis and may be required for some functionality when running th

## SSL in Development

We, at Public Lab use [openssl](https://github.com/ruby/openssl) gem to provide SSL (Secure Sockets Layer) for the secure connection in the development mode. You can run the https connection on the localhost by following the following steps:
At Public Lab we use the [openssl](https://github.com/ruby/openssl) gem to provide SSL (Secure Sockets Layer) for a secure connection (https) in the development mode. You can run the https connection on localhost through the following steps:
1. Use `passenger start --ssl --ssl-certificate config/localhost.crt --ssl-certificate-key config/localhost.key --ssl-port 3001`.
2. Open up https://localhost:3001.
3. Add security exceptions from the advance settings of the browser.
Expand All @@ -147,9 +144,9 @@ Secure connection is needed for OAuth authentication etc.

## Login

Once you complete the installation, use any of these credentials to login in to the PL website in your local development / testing environment to gain additional permissions for only logged in users. Each one comes with its own set of permissions, but besides that the experience across them is pretty much the same.
Once you complete the installation, use any of these credentials to login in to the PL website in your local development / testing environment to gain additional permissions for logged in users only. Each one comes with its own set of permissions; nevertheless, the experience across them is pretty much the same.

**username**: `admin`, `moderator`, or `user`
**username**: `admin`, `moderator`, or `user`

**password**: `password`

Expand All @@ -168,10 +165,10 @@ Click [here](https://github.com/publiclab/plots2/blob/main/doc/TESTING.md) for a
1. We are using [Whenever](https://github.com/javan/whenever) gem to schedule cron jobs.
2. All the cron jobs are written in easy ruby syntax using this gem and can be found in config/schedule.rb.
2. Go to the config/schedule.rb file to create and modify the cron jobs.
3. [Click here](https://github.com/javan/whenever) to know about how to write cron jobs.
3. [Click here](https://github.com/javan/whenever) to learn more about how to write cron jobs.
4. After updating config/schedule.rb file run the command `whenever --update-crontab` to update the cron jobs.
5. To see the installed list of cron jobs use command `crontab -l`
6. For more details about this gem, visit the official repository of whenever gem.
6. For more details about this gem, visit the official repository of the [Whenever](https://github.com/javan/whenever) gem.


## Bundle exec
Expand All @@ -184,18 +181,19 @@ Adding `bundle exec` ensures you're using the version of passenger you just inst

## Reply-by-email

Public Lab now supports reply by email to comment feature. For more details regarding it go to the [email documentation](https://github.com/publiclab/plots2/blob/main/doc/EMAIL.md)
Public Lab now supports "reply by email to comment" feature. For more details, go to the [email documentation](https://github.com/publiclab/plots2/blob/main/doc/EMAIL.md)


## Bugs and support

To report bugs and request features, please use the GitHub issue tracker provided at https://github.com/publiclab/plots2/issues
To report bugs and request features, please use the [GitHub issue tracker](https://github.com/publiclab/plots2/issues)

For additional support, join the Public Lab website and mailing list at http://publiclab.org/lists or for urgent requests, email web@publiclab.org
For additional support, join the Public Lab website and mailing list at http://publiclab.org/lists.
For urgent requests, email web@publiclab.org

## Recaptcha

This application uses RECAPTCHA via the recaptcha gem in production only. For more information, click [here](https://github.com/publiclab/plots2/blob/main/doc/RECAPTCHA.md).
This application uses RECAPTCHA via the recaptcha gem in production only. For more information, [click here](https://github.com/publiclab/plots2/blob/main/doc/RECAPTCHA.md).

## Internationalization

Expand All @@ -206,7 +204,7 @@ To see it in action, click on the 'Language' drop-down located in the footer sec
Translations are arranged in the YAML files [here](https://github.com/publiclab/plots2/tree/main/config/locales), which are
set in a similar way to [views](https://github.com/publiclab/plots2/tree/main/app/views) files. An example for adding translations can be found [here](http://guides.rubyonrails.org/i18n.html#adding-translations).

Since the implementation of our new [Translation system](https://github.com/publiclab/plots2/issues/5737), we now use the `translation()` helper, [found here](https://github.com/publiclab/plots2/blob/438b649669b2029d01437bec9eb2826cf764851b/app/helpers/application_helper.rb#L141-L153). This provides some extra translation features such as inserting a prompt visible to site visitors if no translation exists yet.
Since the implementation of our new [Translation system](https://github.com/publiclab/plots2/issues/5737), we now use the `translation()` helper, [found here](https://github.com/publiclab/plots2/blob/438b649669b2029d01437bec9eb2826cf764851b/app/helpers/application_helper.rb#L141-L153). This provides some extra translation features such as inserting a prompt visible to site visitors if no translation exists yet.

To add new languages or for additional support, please write to plots-dev@googlegroups.com

Expand All @@ -223,20 +221,20 @@ Help improve Public Lab software!
* We're specifically asking for help with issues labelled with [help-wanted](https://github.com/publiclab/plots2/labels/help-wanted) tag
* Find lots of info on contributing at http://publiclab.org/wiki/developers
* Review specific contributor guidelines at http://publiclab.org/wiki/contributing-to-public-lab-software
* Some devs hang out in http://publiclab.org/chat (irc webchat)
* Join our gitter chat at https://gitter.im/publiclab/publiclab
* Try out some supportive tasks https://github.com/publiclab/plots2/wiki/Supportive-Tasks
* Some devs hang out in the [irc webchat](http://publiclab.org/chat)
* Join our [gitter chat](https://gitter.im/publiclab/publiclab)
* Try out some [supportive tasks](https://github.com/publiclab/plots2/wiki/Supportive-Tasks)
* Get involved with our weekly community check-ins. For guidelines: [https://github.com/publiclab/plots2/tree/main/doc/CHECKINS.md
](https://github.com/publiclab/plots2/tree/main/doc/CHECKINS.md)
* You can help us by opening first timers issues or fto. The template for opening an issue can be found https://docs.google.com/document/d/1dO-CAgModEGM5cOaMmcnBh2pEON0hv_rH3P2ou2r1eE/edit
* You can help us by opening first timers issues or fto. The template for opening an issue can be found at https://docs.google.com/document/d/1dO-CAgModEGM5cOaMmcnBh2pEON0hv_rH3P2ou2r1eE/edit

## First Time?

New to open source/free software? Here is a selection of issues we've made **especially for first-timers**. We're here to help, so just ask if one looks interesting : https://code.publiclab.org

[Here](https://publiclab.org/notes/warren/11-22-2017/use-git-and-github-to-contribute-and-improve-public-lab-software) is a link to our Git workflow.

## Let the code be with you.
## Let the code be with you.
### Happy opensourcing. :smile:

<hr>
Expand Down

0 comments on commit 0ed4fc8

Please sign in to comment.