From 2d5076a515a1da5fe859ada76123c1f3a43e13f8 Mon Sep 17 00:00:00 2001 From: r-i-c-h Date: Tue, 22 Jan 2019 20:25:32 -0800 Subject: [PATCH 1/2] An onboarding document that NEEDS REVISION --- .../Getting Started with Open Disclosure.md | 85 +++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 Documentation/Getting Started with Open Disclosure.md diff --git a/Documentation/Getting Started with Open Disclosure.md b/Documentation/Getting Started with Open Disclosure.md new file mode 100644 index 00000000000..24d8bfe26a7 --- /dev/null +++ b/Documentation/Getting Started with Open Disclosure.md @@ -0,0 +1,85 @@ +# Getting started with Open Disclosure + +This is a list of resources used by Open Oakland's **_[Open Disclosure]_** team + instructions to build the site on your own computer. The core technologies we use in the project are [Ruby], [Jekyll] (a Ruby/Liquid-based static site CMS), [CircleCI], [Node.js], a smidge of Python, and a teeny bit of React. *Don't worry* if you don't know things on the list (or if you've never even written a line of code) because we try to be inclusive and there are always tasks to be [re]done regardless of your technical background. Our data comes from [public-sources] and is augmented by a [shared google sheet] we use for manually aggregating information other references. For more information about "how the site works," see the [front-end README], [the site's FAQ], or our [campaign-finance wiki]. + +* **Our Website**: https://www.opendisclosure.io +* **GitHub Repositories**: + * **Front-End Repo**: https://github.com/caciviclab/odca-jekyll + * **Back-End Repo**: https://github.com/caciviclab/disclosure-backend-static + +## Communication Resources +* **Slack**: Join the Open Oakland Slack at `openoakland.slack.com`, then join our specific `#open-disclosure` channel +* **Waffle Board** (Kaban/Trello-style task-board): https://waffle.io/caciviclab/disclosure-backend + +## People To Know? +Lots of people have worked on Open Disclosure in its 2+ years of existance (thanks for joining!), but if you *really* want to know "the deal" try these folks (@slack-Ids from openoakland.slack.com) + +* _Project Leads_: Tom Dooner(@tdooner) Aaron Borden(@adborden) +* _Designer_: :warning::warning::warning: +* _City Liason_: :warning::warning::warning: +* ???: :warning::warning::warning: +* +* + +--- + +# How to build the site on your machine + +Clone _*both*_ the back and front-end repos into the same parent directory. :warning: The front-end ***requires*** that the back-end directory be a sibling _specifically named_ `..\disclosure-backend-static` :warning: in order to build as it is hardcoded that way in the gulpfile. + +Dependencies you should already have installed: [Ruby **2.3.4**], [Bundler], +[Make], +[Node 8.9+], +[ImageMagick] (Only need for production builds?? :warning: ?? **TODO** ?? :warning:),Python ?, [PostgreSQL] (only needed for back-end builds??) + +## ** Build the Front-End ** +(You did see the warning above that you'll need both repositories, right?) + +1. **1st-time only**: `cd` into the front-end directory, run `make setup`, then run `make build`. + +2. **Update** your local data resources with `make pull-finance` + +3. **Rebuild**/**Start Local Server** - *`make serve`*, then the site should be at http://localhost:4000/ + +4. After making any changes you must run Front-End tests with `make test`. + +## ** Build the Back-End ** +If you are only doing front-end work, **building the entire back-end is not necessary** - you just need the base files to exist on your machine so feel free to skip this. + +* **1st-time only**: `cd disclosure-backend-static` and run the following three commands one-at-a-time: + +``` +sudo pip install -r requirements.txt +gem install pg bundler +bundle install +``` + +* **Update Data**: You *do not need to do this every time* - It takes a while to pull the latest information and since it's fairly static data (the real site only updates its data once every 12hrs) you only need to do this "every so often": + * 1) `make download` - Download raw data files from netfile and our [shared google sheet] + * 2) `make import` - Import data for processing + * 3) `make process` - Run the calculators and put output in the "build" folder + +* **Debugging** - If you need it, `make run` will serve the static JSON files via a local web server + +## Making Changes / Development Process + +Notes on our development approach and preferred coding style are written in [ :warning: ** TODO ** :warning: CONTRIBUTING.md ] + +tldr; - To work on the code, create and switch to a new branch in which you can do your work and make changes. When you are ready to merge your code, push your branch up to GitHub, go to the website and click the button in order to "Open a New Pull Request". Another member will review your code to approve the merge request. + +[Bundler]: https://bundler.io/ +[campaign-finance wiki]: https://github.com/caciviclab/campaign-finance-wiki +[CircleCI]: https://circleci.com/gh/caciviclab/odca-jekyll +[front-end README]: https://github.com/caciviclab/odca-jekyll/blob/master/README.md +[ImageMagick]: https://imagemagick.org/script/download.php +[Jekyll]: https://jekyllrb.com/ +[Make]: https://www.gnu.org/software/make/ +[Node 8.9+]: https://nodejs.org/en/download/ +[Node.js]: https://nodejs.org/ +[Open Disclosure]: https://www.opendisclosure.io/ +[PostgreSQL]: https://www.postgresql.org/download/ +[public-sources]: https://ssl.netfile.com/static/agency/coak/ +[Ruby]: https://www.ruby-lang.org/en/downloads/ +[Ruby **2.3.4**]: https://www.ruby-lang.org/en/downloads/ +[shared google sheet]: https://docs.google.com/spreadsheets/d/1vJR8GR5Bk3bUQXziPiQe7to1O-QEm-_5GfD7hPjp-Xc/edit?usp=sharing +[the site's FAQ]: https://www.opendisclosure.io/faq/ \ No newline at end of file From 934a60c6862b4dd61eae622af53b2c9053212a41 Mon Sep 17 00:00:00 2001 From: r-i-c-h Date: Tue, 5 Feb 2019 21:32:54 -0800 Subject: [PATCH 2/2] Made fixes per github.com feedback --- .../Getting Started with Open Disclosure.md | 63 +++++++++---------- 1 file changed, 30 insertions(+), 33 deletions(-) diff --git a/Documentation/Getting Started with Open Disclosure.md b/Documentation/Getting Started with Open Disclosure.md index 24d8bfe26a7..90a04ca9d5e 100644 --- a/Documentation/Getting Started with Open Disclosure.md +++ b/Documentation/Getting Started with Open Disclosure.md @@ -14,38 +14,17 @@ This is a list of resources used by Open Oakland's **_[Open Disclosure]_** team ## People To Know? Lots of people have worked on Open Disclosure in its 2+ years of existance (thanks for joining!), but if you *really* want to know "the deal" try these folks (@slack-Ids from openoakland.slack.com) -* _Project Leads_: Tom Dooner(@tdooner) Aaron Borden(@adborden) -* _Designer_: :warning::warning::warning: -* _City Liason_: :warning::warning::warning: -* ???: :warning::warning::warning: -* -* - ---- +* _Project Leads_: Tom Dooner(@tdooner) & Aaron Borden(@adborden) +* _Designer_: Elina Rubuliak (@elina) +* _City Liason_: Suzanne Doran (@sfdoran) # How to build the site on your machine -Clone _*both*_ the back and front-end repos into the same parent directory. :warning: The front-end ***requires*** that the back-end directory be a sibling _specifically named_ `..\disclosure-backend-static` :warning: in order to build as it is hardcoded that way in the gulpfile. - -Dependencies you should already have installed: [Ruby **2.3.4**], [Bundler], -[Make], -[Node 8.9+], -[ImageMagick] (Only need for production builds?? :warning: ?? **TODO** ?? :warning:),Python ?, [PostgreSQL] (only needed for back-end builds??) - -## ** Build the Front-End ** -(You did see the warning above that you'll need both repositories, right?) - -1. **1st-time only**: `cd` into the front-end directory, run `make setup`, then run `make build`. +Clone _**both**_ the back and front-end repos into the same parent directory. :warning: The front-end ***requires*** that the back-end directory be a sibling _specifically named_ `../disclosure-backend-static` :warning: in order to build as it is hardcoded that way in the gulpfile. -2. **Update** your local data resources with `make pull-finance` - -3. **Rebuild**/**Start Local Server** - *`make serve`*, then the site should be at http://localhost:4000/ - -4. After making any changes you must run Front-End tests with `make test`. +Dependencies you should have installed before starting this process: [Ruby **2.3.4**], [Bundler], [Make], [Node 8.9+], [ImageMagick], [wget], Python v_, [PostgreSQL] ## ** Build the Back-End ** -If you are only doing front-end work, **building the entire back-end is not necessary** - you just need the base files to exist on your machine so feel free to skip this. - * **1st-time only**: `cd disclosure-backend-static` and run the following three commands one-at-a-time: ``` @@ -55,17 +34,34 @@ bundle install ``` * **Update Data**: You *do not need to do this every time* - It takes a while to pull the latest information and since it's fairly static data (the real site only updates its data once every 12hrs) you only need to do this "every so often": - * 1) `make download` - Download raw data files from netfile and our [shared google sheet] - * 2) `make import` - Import data for processing - * 3) `make process` - Run the calculators and put output in the "build" folder + +0. [ Optionally `make clean` to remove previously-downloaded files ] + +1. `make download` - Download raw data files from netfile and our [shared google sheet] + +2. `make import` - Import data for processing + +3. `make process` - Run the calculators and put output in the "build" folder + * **Debugging** - If you need it, `make run` will serve the static JSON files via a local web server -## Making Changes / Development Process +## ** Build the Front-End ** +(You did see the warning above that you'll need both repositories, right?) + +1. **1st-time only** `cd` into the front-end directory, run `make setup` -Notes on our development approach and preferred coding style are written in [ :warning: ** TODO ** :warning: CONTRIBUTING.md ] +2. `make pull-finance` - Update your local data resources + +3. `make build` - Build the site based on the current local files + +4. `make serve` - Rebuilds and *Starts the Local Server*. The site should then be available at http://localhost:4000/ + +5. `make test` - *After making changes*, but before making your pull-request, please make sure all front-end tests pass. + +## Making Changes / Development Process -tldr; - To work on the code, create and switch to a new branch in which you can do your work and make changes. When you are ready to merge your code, push your branch up to GitHub, go to the website and click the button in order to "Open a New Pull Request". Another member will review your code to approve the merge request. +To work on the code, create and switch to a new branch in which you can do your work and make changes. When you are ready to merge your code, push your branch up to GitHub, go to the website and click the button in order to "Open a New Pull Request". Please don't merge your own pull-req, another team member will review your code to approve the merge request! [Bundler]: https://bundler.io/ [campaign-finance wiki]: https://github.com/caciviclab/campaign-finance-wiki @@ -82,4 +78,5 @@ tldr; - To work on the code, create and switch to a new branch in which you can [Ruby]: https://www.ruby-lang.org/en/downloads/ [Ruby **2.3.4**]: https://www.ruby-lang.org/en/downloads/ [shared google sheet]: https://docs.google.com/spreadsheets/d/1vJR8GR5Bk3bUQXziPiQe7to1O-QEm-_5GfD7hPjp-Xc/edit?usp=sharing -[the site's FAQ]: https://www.opendisclosure.io/faq/ \ No newline at end of file +[the site's FAQ]: https://www.opendisclosure.io/faq/ +[wget]: https://www.gnu.org/software/wget/ \ No newline at end of file