Here's the intro paragraph.
14 | 15 |And this is a second paragraph, and it has a link!
18 | 19 |That's it.
20 | -------------------------------------------------------------------------------- /using-civic.json/civic.json.template: -------------------------------------------------------------------------------- 1 | { 2 | "conformsTo": "https://github.com/codefordc/guides/blob/master/using-civic.json/specification.md", 3 | "status": "", 4 | "thumbnailUrl": "", 5 | "contact": { 6 | "name":"", 7 | "email":"", 8 | "twitter":"" 9 | }, 10 | "bornAt": "Code for DC", 11 | "geography": "Washington, DC", 12 | "politicalEntity": {}, 13 | "governmentPartner": {}, 14 | "communityPartner": {}, 15 | "type": "", 16 | "data": {}, 17 | "needs": [], 18 | "categories": [], 19 | "moreInfo":"" 20 | } 21 | -------------------------------------------------------------------------------- /civic.json: -------------------------------------------------------------------------------- 1 | { 2 | "status": "Beta", 3 | "thumbnailUrl": "", 4 | "contact": { 5 | "name":"", 6 | "email":"", 7 | "twitter":"@stvnrlly" 8 | }, 9 | "bornAt": "Code for DC", 10 | "geography": "DC", 11 | "politicalEntity": {}, 12 | "governmentPartner": {}, 13 | "communityPartner": {}, 14 | "type": "Guide", 15 | "needs": [ 16 | {"need":"Guide translation"}, 17 | {"need":"Resource submissions"}, 18 | {"need":"User testing"} 19 | ], 20 | "categories": [ 21 | {"category":"Guide"}, 22 | {"category":"Meta project"} 23 | ], 24 | "moreInfo":"" 25 | } 26 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | WARNING: This repo is in the process of being deprecated and absorbed into other repos. With the exception of the Github guide, the guides have been incorporated directly into Code for DC's website, [here](https://github.com/codefordc/codefordc-2.0/tree/master/_resources). 2 | 3 | # Guides 4 | 5 | The goal of this repo is to help you learn how to do stuff. 6 | 7 | ## Git and Github 8 | 9 | Most of Code for DC's projects use a site called Github to hold their code. If you're new to Github, check out our guide to get up and running. 10 | 11 | ## Contributing to this repo 12 | 13 | This is a group effort! If you have information to add, let us know by opening an issue or submitting a pull request. If you don't know how to do that, check out the appropriate `getting-started` guide for your machine in [learning](learning/) 14 | 15 | This repo is dedicated to the public domain under a [CC0 license](LICENSE.md). By making contributions to this repo, you agree to dedicate those contributions to the public domain, as well. 16 | -------------------------------------------------------------------------------- /graffiti.md: -------------------------------------------------------------------------------- 1 | # Graffiti 2 | 3 | This is a free-for-all text file. The *.md file extension means that it's a Markdown file. Markdown is a popular format for text editing, as it has very simple formatting options. You can learn more about it [here](http://daringfireball.net/projects/markdown/basics). 4 | 5 | * * * 6 | 7 | Markdown lets you use the extra formatting tools, but it also behaves exactly like a *.txt file in that you can just write stuff in it if that's what you feel like doing. 8 | 9 | Here's some stuff you can do: 10 | - Make stuff **bold** or *italic* 11 | - Highlight `code` 12 | - Put things into lists (ordered or unordered) 13 | - And more 14 | 15 | ``` 16 | ( 17 | ( ( ( )\ ) ( 18 | )\ )\ ) ( )\ ) ( (()/( )\ 19 | (((_) ( (()/( ))\ (()/( ( )( /(_))(((_) 20 | )\___ )\ ((_))((_) /(_)) )\(()\ (_))_ )\___ 21 | ((/ __|((_) _| (_)) (_) _|((_)((_) | ((/ __| 22 | | (__/ _ \/ _` / -_) | _/ _ \ '_| | |) | (__ 23 | \___\___/\__,_\___| |_| \___/_| |___/ \___| 24 | 25 | ``` 26 | 27 | Yep. 28 | -------------------------------------------------------------------------------- /using-civic.json/schema.json: -------------------------------------------------------------------------------- 1 | { 2 | "type":"object", 3 | "properties":{ 4 | "conformsTo":{ 5 | "type":"string", 6 | "required":false, 7 | "pattern":"^https://github\.com/codefordc/guides/blob/master/using-civic\.json/specification\.md$" 8 | }, 9 | "status":{ 10 | "type":"string", 11 | "blank":true 12 | }, 13 | "thumbnailUrl":{ 14 | "type":"string", 15 | "blank":true 16 | }, 17 | "contact":{ 18 | "type":"object", 19 | "properties":{ 20 | "name":{ 21 | "type":"string", 22 | "blank":true 23 | }, 24 | "email":{ 25 | "type":"string", 26 | "blank":true 27 | }, 28 | "twitter":{ 29 | "type":"string", 30 | "blank":true 31 | } 32 | } 33 | }, 34 | "bornAt":{ 35 | "type":"string" 36 | }, 37 | "geography":{ 38 | "type":"string" 39 | }, 40 | "politicalEntity":{ 41 | "type":"object" 42 | }, 43 | "governmentPartner":{ 44 | "type":"object" 45 | }, 46 | "communityPartner":{ 47 | "type":"object" 48 | }, 49 | "type":{ 50 | "type":"string", 51 | "blank":true 52 | }, 53 | "data":{ 54 | "type":"object", 55 | "required":false 56 | }, 57 | "needs":{ 58 | "type":"array" 59 | }, 60 | "categories":{ 61 | "type":"array" 62 | }, 63 | "moreInfo":{ 64 | "type":"string", 65 | "blank":true 66 | } 67 | } 68 | } 69 | -------------------------------------------------------------------------------- /codefordc-blog/make-a-blog-post.md: -------------------------------------------------------------------------------- 1 | # Make a Blog Post 2 | 3 | The Code for DC blog is open for contributions for the community. Here's how you do it: 4 | 5 | ## Propose your post 6 | 7 | Before you start, you may want to run your idea by [Matt](mailto:mbailey@codeforamerica.org) to make sure that it is a good fit for the blog. 8 | 9 | ## Fork the website repo 10 | 11 | If you haven't already, go to the [site's repo](https://github.com/codefordc/codefordc-2.0) and make your own fork. This is your personal copy to do as you wish, and nothing will affect the public site until your changes are merged into the original repo (see below). 12 | 13 | ## Create a new file for your post and add your avatar 14 | 15 | In a Jekyll site like Code for DC's, blog posts live in the `blog` folder. There are two folders there: `_drafts` and `_posts`. If you were working on a live version of the site, you'd use the `_drafts` folder to hide your post until it was ready, but since you're on a separate fork you should just work in `_posts`. 16 | 17 | Create a new file in `_posts`, with the name `yyyy-mm-dd-your-post-title`. You can use either the `.md` or `.html` file extension, depending on how you want to write your post. 18 | 19 | You should also choose an avatar for yourself, and add that to the `images/blog/avatars` folder. 20 | 21 | ## Write your post 22 | 23 | Certain things, like the title, author info, and post time, are set in what's called the YAML front matter at the top of the post. It looks something like this: 24 | 25 | --- 26 | layout: post 27 | title: "Your Blog Post Title" 28 | post_author: "Your Name" 29 | post_avatar: "your-avatar.jpg" 30 | date: yyyy-mm-dd hh:mm:ss 31 | categories: blog 32 | post_twitter: "@your-twitter" #optional 33 | image: "image.jpg" #optional 34 | description: "A very brief summary of the post" #optional 35 | --- 36 | 37 | For the date field, choose the date that you'd want your post to go up. If you don't have a preference, just put the current date. Make sure that it matches the date in your filename. 38 | 39 | Then, you just need to type up the body of your post. If you'd prefer to set an excerpt for the main page other than the first 50 words, pop a `` tag in where the excerpt should cut off. 40 | 41 | ## Check your work and open a pull request 42 | 43 | Once you've committed your post to your fork of the repo, run jekyll and check that everything looks good: 44 | 45 | jekyll serve --watch --future 46 | 47 | Point your browser to localhost:4000/blog to see your handiwork. When you're ready, open a pull request from your fork to the Code for DC repo. We'll review the post and, if everything is good to go, we'll merge it in and you're done! 48 | -------------------------------------------------------------------------------- /tools.md: -------------------------------------------------------------------------------- 1 | # Tools 2 | 3 | Once you're working on a project, here are some great tools to save you time and energy. 4 | 5 | ## HTML/CSS 6 | 7 | [Bootstrap](http://getbootstrap.com/): CSS framework to make website-building a (relative) breeze 8 | 9 | [Color Wheel](https://kuler.adobe.com/create/color-wheel/): Find colors that look great together 10 | 11 | [Animate.css](http://daneden.github.io/animate.css/): Easy text animations 12 | 13 | ## Licensing your work and collaborating 14 | 15 | Licensing sounds boring, but it's the best way to keep your code open to others. If you don't provide a license, your work is presumed to be fully copyrighted and therefore closed to others. Code for DC recommends keeping your license in a `LICENSE.md` file. If any explanation is necessary for contributions by others, we recommend including that in your readme or in a separate `CONTRIBUTING.md` file. 16 | 17 | [Choose A License](http://choosealicense.com/) 18 | 19 | ## Frameworks for sites and web apps 20 | 21 | Frameworks allow you to create templates and scripts for a dynamic site 22 | 23 | [Jekyll](http://jekyllrb.com/): The web framework used by Github Pages; probably most useful if you are using that for hosting 24 | 25 | [Django](https://www.djangoproject.com/): A full-featured framework built on Python 26 | 27 | [Flask](http://flask.pocoo.org/): Another Python framework; fewer features and less powerful, but simpler to set up 28 | 29 | [Express](http://expressjs.com/guide.html): A Node-based framework 30 | 31 | [Sinatra](http://www.sinatrarb.com/): A Ruby-based framework 32 | 33 | ## Javascript Libraries 34 | 35 | [jQuery](https://jquery.com/): Add interactivity to your site 36 | 37 | [Moment](http://momentjs.com/): Work with dates easily 38 | 39 | [Typeahead](https://twitter.github.io/typeahead.js/): Autocomplete functions for forms 40 | 41 | [Underscore](http://underscorejs.org/): Additional Javascript functionality to make programming simpler 42 | 43 | ## Hosting 44 | 45 | [Heroku](https://www.heroku.com/): Apps with low data needs are free, and the price after that scales with usage 46 | 47 | [Dotcloud](https://www.dotcloud.com/): Another hosting option 48 | 49 | [Github Pages](https://pages.github.com/): Your code already lives there and hosting is free, but all of your information will be out in the open (if passwords, etc. are required, this can be a security risk). 50 | 51 | [Amazon Web Services](https://aws.amazon.com/): Relatively cheap cloud hosting for anything, including static files 52 | 53 | ## Font Families and Images 54 | 55 | [Font Awesome](https://fortawesome.github.io/Font-Awesome/): Easily add icons to your site 56 | 57 | [GSA logos](https://github.com/GSA/logo): Logos for government agencies 58 | 59 | ## Scraping 60 | 61 | [BeautifulSoup (Python)](http://www.crummy.com/software/BeautifulSoup/bs4/doc/) 62 | 63 | [Phantom JS](http://phantomjs.org/) 64 | 65 | ## GIS/Mapping 66 | 67 | [QuantumGIS/QGIS](http://qgis.org/en/site/) 68 | 69 | [CartodDB](http://cartodb.com) 70 | 71 | [Mapbox](https://www.mapbox.com) 72 | 73 | TileMill 74 | 75 | [Leaflet](http://leafletjs.com/) 76 | 77 | [Color Brewer](http://colorbrewer2.org/): Find colors for maps and data viz 78 | 79 | ## [Data viz](http://selection.datavisualization.ch/) 80 | 81 | [D3.js](http://d3js.org/) 82 | 83 | [Tableau](http://www.tableausoftware.com/) 84 | 85 | [Raphaël](http://raphaeljs.com/) 86 | 87 | ## Reading/extracting PDFs 88 | 89 | Tesseract 90 | 91 | Mechanical Turk 92 | 93 | [Tabula](http://tabula.nerdpower.org/) 94 | 95 | ## Data cleaning/munging/conversion 96 | 97 | [Google Refine/Open Refine](https://github.com/OpenRefine/OpenRefine) 98 | 99 | Datawrangler 100 | 101 | [Mr. Data Convertor](http://shancarter.github.io/mr-data-converter/) 102 | 103 | ## Interacting with Government Agencies 104 | 105 | FOIA 106 | 107 | ## APIs 108 | 109 | [ProgrammableWeb](http://www.programmableweb.com/category/all/apis): Extensive directory of APIs 110 | 111 | Census 112 | 113 | [Sunlight](http://sunlightfoundation.com/api/): The Open States API may be of particular interest to DC-based projects 114 | 115 | SeeClickFix 116 | -------------------------------------------------------------------------------- /further-reading.md: -------------------------------------------------------------------------------- 1 | # Resources 2 | 3 | There's always more to learn. Here are some places to get started. 4 | 5 | - [Definitions](#definitions) 6 | - [General Guides](#general-guides) 7 | - [Command Line](#command-line) 8 | - [Git](#git) 9 | - [Python](#python) 10 | - [Ruby](#ruby) 11 | - [Javascript](#javascript) 12 | - [Web Development (HTML/CSS and beyond)](#web-development) 13 | - [Web Hosting](#web-hosting) 14 | - [R](#r) 15 | - [Geographic Information Systems (GIS)](#gis-qgis) 16 | 17 | ## Definitions 18 | 19 | [Project Open Data](https://project-open-data.github.io/glossary/) 20 | 21 | [Open Data Handbook](http://opendatahandbook.org/en/glossary.html) 22 | 23 | [W3](http://www.w3.org/TR/2013/NOTE-ld-glossary-20130627/) 24 | 25 | [United States Glossary](https://github.com/unitedstates/glossary/): legal and Congress-related terms 26 | 27 | ## General Guides 28 | 29 | [Lifehacker's Learn to Code](http://lifehacker.com/5744113/learn-to-code-the-full-beginners-guide): general programming guide; explains variables, data types, arrays, logic statements, functions, etc 30 | 31 | [List of Free Programming Books](https://github.com/vhf/free-programming-books/blob/master/free-programming-books.md#professional-development) 32 | 33 | [Become a Programmer](http://programming-motherfucker.com/become.html): offensive but useful links 34 | 35 | [CodeAvengers](http://www.codeavengers.com/) 36 | 37 | ## Command Line 38 | 39 | [A Command Line Primer for Beginners](http://lifehacker.com/5633909/who-needs-a-mouse-learn-to-use-the-command-line-for-almost-anything): Good general command line primer 40 | 41 | [The designer’s guide to the OSX command prompt](http://wiseheartdesign.com/articles/2010/11/12/the-designers-guide-to-the-osx-command-prompt/): Mac command line guide 42 | 43 | [Command Prompt Basics - A Getting Started Guide](http://dosprompt.info/): Windows command line guide 44 | 45 | ## Git 46 | 47 | [Try Git](https://try.github.io/levels/1/challenges/1): a quick hands-on course, going more in-depth with git commands 48 | 49 | [Git Overview](http://git-scm.com/book/en/Getting-Started-About-Version-Control): an explanation of how git does version control, so you can understand conceptually what the program is doing 50 | 51 | [Git Screencast](http://vimeo.com/16395537): see git in action 52 | 53 | [Visual Git](https://marklodato.github.io/visual-git-guide/index-en.html): a graphical explanation, in case you prefer a visual approach 54 | 55 | [GitHub Cheatsheet](https://github.com/tiimgreen/github-cheat-sheet) 56 | 57 | [A Guide to Github Pages](http://www.thinkful.com/learn/a-guide-to-using-github-pages/) 58 | 59 | [Git and GitHub Glossary](https://help.github.com/articles/github-glossary/) 60 | 61 | ## Python 62 | 63 | [Codecademy](http://www.codecademy.com/tracks/python): an online course with lessons and exercises 64 | 65 | [Learn Python the Hard way](http://learnpythonthehardway.org/): great way to learn python 66 | 67 | ## Ruby 68 | 69 | [Ruby in 20 Minutes](https://www.ruby-lang.org/en/documentation/quickstart/): a quick introduction to the language 70 | 71 | [Codecademy](http://www.codecademy.com/tracks/ruby): an online course with lessons and exercises 72 | 73 | [why's (poignant) guide to ruby](http://www.rubyinside.com/media/poignant-guide.pdf) (PDF): it's incredible 74 | 75 | ## Javascript 76 | 77 | [Eloquent JavaScript](http://eloquentjavascript.net/contents.html) 78 | 79 | ## Web development 80 | 81 | [bentobox.io](http://www.bentobox.io/): learn everything you need to know about web development and more (html,css,js,git,sql,sublime,jquery,etc) 82 | 83 | [Mozilla Developer Network Web Development](https://developer.mozilla.org/en-US/docs/Web_Development): great intro to web development (html,css,javascript,etc) 84 | 85 | [W3C Schools](http://www.w3schools.com/) 86 | 87 | ## Web Hosting 88 | 89 | [Amazon Web Services EC2 For Poets](http://ec2.forpoets.org/) 90 | 91 | ## R 92 | 93 | [Try R](http://tryr.codeschool.com/): Learn R from your browser 94 | 95 | [R Twotorials](http://www.twotorials.com/) 96 | 97 | [Beginner's Guide to R](http://www.computerworld.com/s/article/9239625/Beginner_s_guide_to_R_Introduction) 98 | 99 | [An Introduction to R](http://cran.r-project.org/doc/manuals/R-intro.pdf) 100 | 101 | [The Guerilla Guide to R](http://www.r-bloggers.com/the-guerilla-guide-to-r/) 102 | 103 | ## GIS (QGIS) 104 | 105 | [QGIS Basics for Journalists](http://multimedia.journalism.berkeley.edu/tutorials/qgis-basics-journalists/): great introduction to QGIS 106 | -------------------------------------------------------------------------------- /start-a-project.md: -------------------------------------------------------------------------------- 1 | # Start a Project 2 | 3 | So you have a project--or an idea for a project--to make life better for the people of DC and you want to bring it to Code for DC? Awesome! We're glad you thought of us. In order to help us help you, here's what you should do: 4 | 5 | ## Make a Github repo 6 | 7 | You may already have one, but make sure that you have a Github repo for the project. This is true even if the project is still just an idea: a repo saves the space, offers some discussion tools, and makes it possible for other people to begin working on the project. The only document that's really required is a `README` file explaining (1) what the project is and (2) how to run the project locally, if applicable. 8 | 9 | To take the administrative burden off of you, Code for DC can set up a repo for the project in our Github organization. If you want us to do that, just let us know. If you already have a repo, this is still possible: it can be [transferred](https://help.github.com/articles/how-to-transfer-a-repository) into the Code for DC organization without losing any of the commit history or issue. 10 | 11 | ## Choose a license 12 | 13 | This is an important step for the type of open work we do at Code for DC. Without a license, each contribution is copyrighted by the individual author, which can make something of a mess. We recommend using a [CC0 license](https://creativecommons.org/publicdomain/zero/1.0/legalcode) for maximum openness, but there are other popular open-source licenses. You can find one that works for you [here](http://choosealicense.com/). 14 | 15 | Once you've selected a license, you should include the text of that license in a `LICENSE.md` file in the root of your repo. Additionally, you should include language, either in the `README` or a separate `CONTRIBUTING.md` file stating that contributors to the repo agree to license their work under the same license. It's also a good practice to mention the license you've chosen in the `README`, as well. 16 | 17 | If anybody besides you contributed to the project before a license was applied, or if you change the license, make sure to get their approval. This can be done in whatever way works: in person, via email, or even a [Github issue](https://github.com/project-open-data/project-open-data.github.io/pull/135). 18 | 19 | ## Put a `civic.json` file in that repo 20 | 21 | A `civic.json` file is the metadata file of the type of civic-oriented project we work on here at Code for DC. We've made a template to start you off, and it's available right [here](./civic-dot-json/civic.json.template). For instructions on how to fill it out, check out the specifications [here](./civic-dot-json/specification.md). 22 | 23 | ## Let everybody know 24 | 25 | Head over to [the projects page](http://codefordc.org/projects) and submit the project's repo URL to us. We'll pull information from Github and that `civic.json` file and make it look nice. Feel free to send a message out to the [listserv](https://groups.google.com/forum/#!forum/dc-cfa-brigade), as well, explaining what the project is and what sort of help you think is needed. 26 | 27 | ## Bonus: Make contributing easy 28 | 29 | ### Use Common and Accessible Tools 30 | 31 | When choosing the tools that will be used to build the project, consider the startup time that a new recruit will need to learn how to use those tools. Since Code for DC projects are mostly volunteer projects and are open to non-experts, using tools that are common across projects or that are simpler to learn may significantly reduce startup time and increase the number of pull requests you receive. There is a trade-off between cutting-edge and community engagement, so keep that in mind. 32 | 33 | For example, the Code for DC website is built in Jekyll to take advantage of Github Pages. Jekyll has built-in support for Sass, so we have a choice between that and CSS when writing our stylesheets. Sass is pretty useful, but using it would require anybody who wants to work on our CSS to learn an entire new language. As a result, we're sticking with CSS for now to keep things accessible. 34 | 35 | ### Simple Installation 36 | 37 | To allow potential contributors to get up and running on the project quickly, we recommend using tools like the [Chrome Dev Editor](https://chrome.google.com/webstore/detail/chrome-dev-editor-develop/pnoffddplpippgcfjdhbmhkofpnaalpg?hl=en), [Docker](https://www.youtube.com/watch?v=VeiUjkiqo9E), or [Vagrant](https://docs.vagrantup.com/v2/why-vagrant/) to simplify local installation. Less time installing the project means more time getting work done! 38 | -------------------------------------------------------------------------------- /using-civic.json/specification.md: -------------------------------------------------------------------------------- 1 | # `civic.json` Specification 2 | 3 | This is based on the work done by [BetaNYC](https://github.com/BetaNYC/civic.json/blob/master/specification.md). 4 | 5 | ## File Location and contents 6 | 1. `civic.json` shall reside in the root directory of a project's github repository. 7 | 2. `civic.json` shall include a single object represented as JSON, with the key/value pairs outlined below. 8 | 9 | ## Key/Value Pairs 10 | 1. `conformsTo` - a link to the schema used in the `civic.json` file. 11 | 2. `status` - text indicating the status of the project. Any text is allowed, but a selection from the recommended values is advised: 12 | 13 | * `"Ideation"` - Brainstorming phase 14 | * `"Alpha"` - Brainstorming phase 15 | * `"Beta"` - Brainstorming phase 16 | * `"Production"` - Finished Product, development ongoing 17 | * `"Archival"` - Finished Product, development ongoing 18 | 19 | 3. `thumbnailUrl` - a URL to an image associated with the project listing. 20 | 4. `contact` - an object containing `name`, `email`, and `twitter` objects, with each representing the preferred contact information for the project. 21 | 5. `bornAt` - text indicating the name of the event the project was conceived at, if any. Any text is allowed. 22 | 6. `geography` - text indicating the city, state, county, or other geographic entity this project is relevant to. Any text is allowed. 23 | 24 | examples: "Washington, DC", "NYC", "Greater Baltimore" 25 | 7. `politicalEntity` - an object indicating any political entity to which the project is relevant. The key is the entity's name, and the value is the entity's URL. 26 | 27 | example: {"DC Council": "http://www.dccouncil.washington.dc.us/"} 28 | 8. `governmentPartner` - an object indicating any political entity with which the project is working. The key is the entity's name, and the value is the entity's URL. 29 | 30 | example: {"DC Council": "http://www.dccouncil.washington.dc.us/"} 31 | 9. `communityPartner` - an object indicating the community organizations with which the project is working. The key is the org's name, and the value is the org's URL. 32 | 33 | example: {"Bread for the City": "http://www.breadforthecity.org/"} 34 | 10. `type` - text describing the type of project. Any text is allowed, but a selection from the recommended values is advised: 35 | 36 | * `"Web App"` 37 | * `"Mobile App"` 38 | * `"Policy Document"` 39 | * `"Dataset"` 40 | 41 | 11. `data` - an object of "dataset" objects. The key is the name of the dataset, and the value is the dataset's URL. 42 | 12. `needs` - an array of "need" or "want" objects. Needs are considered necessary to the success of the project, while wants are considered enhancements. There is no limit to the number of objects included in a project. 43 | 13. `need` or `want` - text indicating a need or want of the project. This can be a skillset that is needed, or any other resource. Any text is allowed. 44 | 45 | examples: "Web Designer", "Web Hosting", "Political Sponsorship" 46 | 14. `categories` - an array of "category" objects. There is no limit to the number of categories included in a project. 47 | 15. `category` - text indicating the category of the project. Any text is allowed. 48 | 49 | examples: "Land Use", "Transportation", "Politics", "Financial", "Open Data" 50 | 16. `moreInfo` - a URL to a document or site with more information about the project, such as a Hackpad or Google Doc. 51 | 52 | ## Example civic.json 53 | 54 | ``` 55 | { 56 | "conformsTo": "https://raw.githubusercontent.com/codefordc/guides/master/using-civic.json/specification.md", 57 | "status": "Production", 58 | "thumbnailUrl":"http://example.com/static/img/favicon.png", 59 | "contact": 60 | { 61 | "name": "", 62 | "email": "contactus@example.com", 63 | "twitter": "@codefordc" 64 | }, 65 | "bornAt": "Code for DC", 66 | "geography": "DC", 67 | "communityPartner": {"Community Organization":"http://example.com"}, 68 | "politicalEntity": {"Office of Something":"http://something.dc.gov/"}, 69 | "governmentPartner": {}, 70 | "type": "Web App", 71 | "data": { 72 | "A Useful Dataset":"http://example.com/dataset", 73 | "Another Dataset":"http://example.com/otherstuff" 74 | }, 75 | "needs": [ 76 | {"need":"Ruby on Rails"}, 77 | {"need":"Spreadsheet Experts"} 78 | ], 79 | "categories": [ 80 | {"category":"Politics"}, 81 | {"category":"Government"}, 82 | {"category":"Open Data"} 83 | ], 84 | "moreInfo": "" 85 | } 86 | ``` 87 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | Statement of Purpose 2 | 3 | The laws of most jurisdictions throughout the world automatically confer exclusive Copyright and Related Rights (defined below) upon the creator and subsequent owner(s) (each and all, an "owner") of an original work of authorship and/or a database (each, a "Work"). 4 | 5 | Certain owners wish to permanently relinquish those rights to a Work for the purpose of contributing to a commons of creative, cultural and scientific works ("Commons") that the public can reliably and without fear of later claims of infringement build upon, modify, incorporate in other works, reuse and redistribute as freely as possible in any form whatsoever and for any purposes, including without limitation commercial purposes. These owners may contribute to the Commons to promote the ideal of a free culture and the further production of creative, cultural and scientific works, or to gain reputation or greater distribution for their Work in part through the use and efforts of others. 6 | 7 | For these and/or other purposes and motivations, and without any expectation of additional consideration or compensation, the person associating CC0 with a Work (the "Affirmer"), to the extent that he or she is an owner of Copyright and Related Rights in the Work, voluntarily elects to apply CC0 to the Work and publicly distribute the Work under its terms, with knowledge of his or her Copyright and Related Rights in the Work and the meaning and intended legal effect of CC0 on those rights. 8 | 9 | 1. Copyright and Related Rights. A Work made available under CC0 may be protected by copyright and related or neighboring rights ("Copyright and Related Rights"). Copyright and Related Rights include, but are not limited to, the following: 10 | 11 | the right to reproduce, adapt, distribute, perform, display, communicate, and translate a Work; 12 | moral rights retained by the original author(s) and/or performer(s); 13 | publicity and privacy rights pertaining to a person's image or likeness depicted in a Work; 14 | rights protecting against unfair competition in regards to a Work, subject to the limitations in paragraph 4(a), below; 15 | rights protecting the extraction, dissemination, use and reuse of data in a Work; 16 | database rights (such as those arising under Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, and under any national implementation thereof, including any amended or successor version of such directive); and 17 | other similar, equivalent or corresponding rights throughout the world based on applicable law or treaty, and any national implementations thereof. 18 | 2. Waiver. To the greatest extent permitted by, but not in contravention of, applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and unconditionally waives, abandons, and surrenders all of Affirmer's Copyright and Related Rights and associated claims and causes of action, whether now known or unknown (including existing as well as future claims and causes of action), in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each member of the public at large and to the detriment of Affirmer's heirs and successors, fully intending that such Waiver shall not be subject to revocation, rescission, cancellation, termination, or any other legal or equitable action to disrupt the quiet enjoyment of the Work by the public as contemplated by Affirmer's express Statement of Purpose. 19 | 20 | 3. Public License Fallback. Should any part of the Waiver for any reason be judged legally invalid or ineffective under applicable law, then the Waiver shall be preserved to the maximum extent permitted taking into account Affirmer's express Statement of Purpose. In addition, to the extent the Waiver is so judged Affirmer hereby grants to each affected person a royalty-free, non transferable, non sublicensable, non exclusive, irrevocable and unconditional license to exercise Affirmer's Copyright and Related Rights in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the "License"). The License shall be deemed effective as of the date CC0 was applied by Affirmer to the Work. Should any part of the License for any reason be judged legally invalid or ineffective under applicable law, such partial invalidity or ineffectiveness shall not invalidate the remainder of the License, and in such case Affirmer hereby affirms that he or she will not (i) exercise any of his or her remaining Copyright and Related Rights in the Work or (ii) assert any associated claims and causes of action with respect to the Work, in either case contrary to Affirmer's express Statement of Purpose. 21 | 22 | 4. Limitations and Disclaimers. 23 | 24 | No trademark or patent rights held by Affirmer are waived, abandoned, surrendered, licensed or otherwise affected by this document. 25 | Affirmer offers the Work as-is and makes no representations or warranties of any kind concerning the Work, express, implied, statutory or otherwise, including without limitation warranties of title, merchantability, fitness for a particular purpose, non infringement, or the absence of latent or other defects, accuracy, or the present or absence of errors, whether or not discoverable, all to the greatest extent permissible under applicable law. 26 | Affirmer disclaims responsibility for clearing rights of other persons that may apply to the Work or any use thereof, including without limitation any person's Copyright and Related Rights in the Work. Further, Affirmer disclaims responsibility for obtaining any necessary consents, permissions or other rights required for any use of the Work. 27 | Affirmer understands and acknowledges that Creative Commons is not a party to this document and has no duty or obligation with respect to this CC0 or use of the Work. 28 | -------------------------------------------------------------------------------- /learn-github/learn-github-osx.md: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | Welcome! This guide assumes that you are a total newcomer (but, hopefully, you know how to use a computer). We're not going to get too in depth about anything, but should get you up and running with everything you need to begin working. Once you're set up, you can then [dive deeper](learning-resources.md) into any of the individual areas. If you are already familiar with an aspect, feel free to skip it. 4 | 5 | This is the plan: 6 | 7 | 1. [The Command Line](#the-command-line) 8 | 2. [Working with git and Github](#working-with-git-and-github) 9 | 3. [Editing!](#editing) 10 | 4. [Making a Pull Request](#making-a-pull-request) 11 | 12 | We're going to use those skills to edit this very repo! At the end, you'll have your own personal ("local" is the jargon) copy of this repo set up on your computer, allowing you to edit and explore freely. Then, using pull requests, you'll propose a change to this repo from changes you made to your personal copy. That might sound fancy now, but we're going to walk through the whole process and make it easy. 13 | 14 | If something goes wrong along the way, use Google. Google is your friend. Pasting in the error code should get you an explanation of what went wrong and how to fix it. (Often, the answer will be somewhere on Stack Overflow). 15 | 16 | Okay, let's begin. 17 | 18 | ## The Command Line 19 | 20 | On a Mac, open up your Terminal program. It should look something like this: 21 | 22 |  23 | 24 | ### Traversing the CLI 25 | 26 | This is your home directory (hence the little :house: up on top). In command line terms, your home directory is notated as `~`. We're going to use this interface to navigate your file structure and run some commands. Here are the tools we'll use to do that: 27 | 28 | `ls [directory]`: displays the contents of the directory specified (if none specified, the current directory) 29 | 30 | `cd [directory]`: changes to the directory specified (if none specified, the home directory) 31 | 32 | `mkdir [directory]`: creates a new directory 33 | 34 | `touch [file]`: creates a file 35 | 36 | `pwd`: shows you your location in the file system 37 | 38 | We're going to need to tell these commands where to do things. Here's how we do that: 39 | 40 | The current directory is notated as `.`. The directory above that is notated as `..`. For example, the structure of this repo is: 41 | 42 | . 43 | ├── LICENSE.md 44 | ├── README.md 45 | ├── civic.json 46 | ├── further-reading.md 47 | ├── graffiti.md 48 | ├── learn-github 49 | │ ├── hello-world 50 | │ │ ├── hello-world.py 51 | │ │ └── hello-world.rb 52 | │ ├── img 53 | │ │ ├── github-forked-clone.png 54 | │ │ ├── github-forked-owner.png 55 | │ │ ├── github-pullrequest-approval.png 56 | │ │ ├── github-pullrequest-message.png 57 | │ │ ├── github-pullrequest-start.png 58 | │ │ ├── github-repo-fork.png 59 | │ │ ├── github-repo-issues.png 60 | │ │ ├── github-repo-owner.png 61 | │ │ └── terminal-start.png 62 | │ └── learn-github-osx.md 63 | └── tools.md 64 | 65 | So, if I'm in the root of the directory and want to move to the `img` folder, I type `cd img` or `cd ./img` into the terminal. I can then run `ls` to see that `terminal-start.png` is in the current directory. 66 | 67 | In all cases, the `tab` key is your friend. It will autocomplete commands and paths and, if there are multiple options, it will show you those options. 68 | 69 | ### Creating a Folder for Programming Stuff 70 | 71 | It's useful to put all of your programming projects in one directory (and it makes for a convenient exercise for our purposes), so let's start with that. 72 | 73 | First, let's take a look around the home directory, using `ls`. 74 | 75 | $ ls 76 | 77 | You should see something like this: 78 | 79 | Applications Desktop Documents Library Movies Music Pictures Public 80 | 81 | Those are all of the directories you know and love from the file explorer. To peek within any of them, simply enter `ls` followed by the directory name. Give it a shot! Note that no matter how much you `ls`, you return to the same directory for the next command; only `cd` can move you around. 82 | 83 | Now, you'll need to decide where in your file structure you'd like to put it. This is a personal choice! Where it is doesn't matter so much as you being able to easily locate it. I keep mine in a Dropbox-type folder, so that my files sync across my devices. Other people might want to put it in their `Documents` folder, or to just put it in the home directory. Choose whatever works for you. 84 | 85 | Once you've decided where to put the folder, we'll need to create it. Use `mkdir` to do this, which will look something like this: 86 | 87 | $ mkdir Documents/Programming 88 | 89 | Remember that the path will vary based on where you're putting the folder. If you already tried some of those commands and are no longer in the home directory, you can use the full path instead, like this: 90 | 91 | $ mkdir ~/Documents/Programming 92 | 93 | ### Making files 94 | 95 | Now that you have this cool new folder, let's go check it out! If you're not sure where you are, remember that you can use `pwd` to tell you your location. If you're not in the home directory, you can change to it with `cd` or `cd ~`. Using `cd`, change to your programming folder. In our example, this would go like this: 96 | 97 | $ cd Documents/Programming 98 | 99 | Remember that you can always go to the directory above the current one by running `cd ..`. This directory is empty, so running `ls` here won't return anything. Let's change that by creating a new file. 100 | 101 | $ touch hello-world.txt 102 | 103 | That's it, you made a file! Now, let's write in that file. There are two ways to go about this. First, you can open it in your default text editor: 104 | 105 | $ open hello-word.txt 106 | 107 | Second, you can use `echo` to add to it without even leaving the CLI. `echo` is a command that does just that: echoes your input. Thus: 108 | 109 | $ echo 'hello world' 110 | hello world 111 | 112 | By using `>`, we can redirect that output to the file. Thus: 113 | 114 | $ echo 'hello world' > hello-world.txt 115 | 116 | Check the file and you'll see that it's true. 117 | 118 | There are a few other commands that you may want to learn, like `rm`, `cp`, `mv`, and `cat`, but you are now more than prepared for the next step. 119 | 120 | ## Working with git and Github 121 | 122 | In this step, you're going to set up a new command line program called git, get running on Github, and create a local version of this repo to work on. 123 | 124 | Git is a piece of version control software. It allows you to work on the same repository (a group of files, basically) as another person, at the exact same time, without totally messing each other up. It does this by grouping changes into `commits`, which you then `push` to the central repo. You can only `push` if your local versions has all the previous commits. So, if somebody else pushed commits since you last checked, you must `pull` and `merge` those changes into your local copy before you can `push` your new changes. Basically, it's a way to make sure that your new changes are made to the most recent version of the repo. 125 | 126 | That might sound confusing, but it should become clearer as we walk through the process. So, here we go. 127 | 128 | ### Installing git 129 | 130 | Git is a program on your computer, so it needs to be installed. It's not too hard: just go [here](http://git-scm.com/downloads), download the latest version, and install it like any other program. If you'd like to get fancy, you can install it using a package manager like [Homebrew](http://brew.sh/), which makes installation as easy as running `brew install git` on your command line. It's not strictly necessary here, but it might make your life easier down the line. 131 | 132 | Once you've installed git, you should check that everything worked properly. In Terminal, run the command `git`; hopefully, you'll get a brief view of all the options for the command. 133 | 134 | ### Using Github 135 | 136 | As mentioned above, git works by holding a central repo of all of the files, to which people push their changes. That repo has to live somewhere that is accessible to all of those people, and Github is often the service of choice. As you can tell, we're also using Github. So, if you have a Github account, make sure you're logged in. If you don't , go ahead and [sign up](https://github.com/join) and walk through the configuration steps. Then, in order to communicate with Github's servers, you should make sure that you have [SSH keys set up](https://help.github.com/articles/generating-ssh-keys) (this is the hardest step yet, but you can handle it). 137 | 138 | Once you're set up with Github, look around this page (mostly near the top) and you'll notice a few things. 139 | 140 | First, the name of the repo and its owner. This is listed on the page, as well as in the URL. Right below that, in the gray bar, you can check out the commit history of the repo, which can show you which change happened when. For example, [in this repo](https://github.com/codefordc/guides/commits/master), you can see that the [first commit](https://github.com/codefordc/guides/commit/1b08f69b2fd5837af42dc12326bd9394414dfbe5) included a few files, the [second commit](https://github.com/codefordc/guides/commit/4fb3ad2022931b5a057f4ffe0061c832454ce4d1) was a commit from a pull request, the [third commit](https://github.com/codefordc/guides/commit/044f148863601491e1dce26f1f14dc25e4d513b0) merged that commit from a fork of the repo into the Code for DC repo (it might look confusing because @stvnrlly made both commits), and the [fourth commit](https://github.com/codefordc/guides/commit/defc8390dce25e61236f350311e124d0bea80d48) added screenshots and more text to this document. 141 | 142 |  143 | 144 | Second, to the right of the code, the `Issues` and `Pull Requests` tabs. Issues are for discussing ideas and problems with the repo. Check out the [issues for this repo](https://github.com/codefordc/guides/issues) to see what we're discussing; maybe you can help resolve one of them! Pull requests are how you ask to have your commits added to the repo, which we'll cover once you've pushed some commits to your own version of the repo. 145 | 146 |  147 | 148 | Third, the `Fork` button up in the top right. If you don't have push permissions for the repo (unless it's your repo or the owner has granted you push access, you probably don't), the way to collaborate on a repo is to fork it. This copies the repo and creates your own separate version that you control. You can push commits to it as much as you want without affecting the repo from which you forked it. 149 | 150 |  151 | 152 | So, how do you add your code to the main repo? By making a pull request. This tells the repo's owner that you'd like them to merge some of your commits from your fork into the main repo. Before you do that, though, you'll need to make some commits, and that means doing some coding. 153 | 154 | To work on the code, you'll need to get a local copy of the repo. Get started by clicking that `Fork` button, which will take you to your own special version of the repo. As you can see, this repo has the full commit history of the repo you just forked, but it will not include future changes without a pull request. If you go look at [@stvnrlly's fork](https://github.com/stvnrlly/guides), for instance, you'll see that it doesn't have any of the more recent commits to the Code for DC repo, but it does have some commits unique to the fork. 155 | 156 |  157 | 158 | Then, check down in the lower right side of the navbar. You'll see an HTTPS or SSH `clone URL`. 159 | 160 |  161 | 162 | Copy this and head back to the Terminal. There, all you have to do is this: 163 | 164 | $ git clone [that clone URL you just copied] 165 | 166 | A bunch of stuff will happen, and at the end of it you'll have a brand new local copy of your forked repo, ready to be hacked on. 167 | 168 | If you haven't done anything extra, your `Programming` folder should now look something like this: 169 | 170 | . 171 | ├── hello-world.txt 172 | └── guides 173 | 174 | We're going to work on the files in the `guides` directory, so go ahead and `cd` into it. 175 | 176 | ## Editing! 177 | 178 | In order to code, you'll probably want a text editor that understands code. Some options include [TextMate](http://macromates.com/), [Sublime](http://www.sublimetext.com/), or [Atom](https://atom.io/); there are [lots](https://en.wikipedia.org/wiki/Comparison_of_text_editors#Programming_features) to choose from. 179 | 180 | For our purposes, that's pretty much all you'll need. While we're here, though, we might as well check that you have some of the major programming languages installed on your machine. To do this, we're going to run a couple of ["Hello World"](https://en.wikipedia.org/wiki/Hello_world_program) programs, which we've already put in the repo. It should go something like this: 181 | 182 | $ python learning/hello-world/hello-world.py 183 | Hello World! (in Python) 184 | $ ruby learning/hello-world/hello-world.rb 185 | Hello World! (in Ruby) 186 | 187 | You can open those files up in your new text editor to see how that happened. 188 | 189 | Now, let's make some edits. Pick a file that you'd like to edit (or make a new file) and open it in the editor. Feel free to edit anything in the repo; if nothing strikes you, we've included the `graffiti.md` file as a free-for-all text file. 190 | 191 | Once you've made the edits and saved your work, it's time to do some git magic. Start by checking the status of the repo: 192 | 193 | $ git status 194 | 195 | You should get an overview of what files within the repo have been changed. If you edited an existing file, you'll be told that there are `Changes not staged for commit`. If you created a new file, you'll be told that there are `Untracked files`. The message also lets you know that you should `add` them to the staging area in order to commit them. That's a good idea, so let's do it: 196 | 197 | $ git add [the file(s) you want to commit] 198 | 199 | You can run `git add` as many times as you'd like before committing the bundle of changes, as well as removing files from the staging area with `git rm [file]`. After adding, run `git status` again, and you should see that the file(s) are now ready to be committed. Great, let's do that: 200 | 201 | $ git commit -m "message explaining what's in the commit" 202 | 203 | Git requires that you include a message explaining the changes in the commit; usually, a sentence or less should do the trick. 204 | 205 | You can commit as many times as you'd like before pushing those commits to the repo. A good practice is to group similar changes into separate commits, as that will help make the changes clear to others working on the repo (or your future self). 206 | 207 | Ready to push? It's easy: 208 | 209 | $ git push origin master 210 | 211 | In that command, `origin` refers to the version of the repo on Github, and `master` refers to the branch of the repo. Branches are a whole deeper and more awesome layer of git. `master` is usually the name of the default branch and is a good place to keep the "live" version of the repo, while other branches can be set up to develop features (including commiting and pushing) that aren't ready to be incorporated into that live version just quite yet. 212 | 213 | Excellent! You have now edited your repo. Now it's time to request that your changes be pulled back into the original Code for DC version of the repo. 214 | 215 | ## Making a Pull Request 216 | 217 | Back on the Github site, open up your fork of the repo. Remember that `Pull Requests` tab over on the right? Well, now we're going to use it. On that page, just click the `New pull request` button up on the right. You'll end up here: 218 | 219 |  220 | 221 | Github will automatically compare your repo against the Code for DC repo. If everything outside of your committed changes is the same in both repos (this might not be the case if somebody pushed a commit to the file you're working on since you last pulled), Github will tell you that the pull request can be automatically merged, which will help the owner of the other repo. You can (and should) also enter a message explaining what the commits in your pull request will do. Once you're satisfied, hit `Create Pull Request`. 222 | 223 |  224 | 225 | That's it! On the other side, your pull request will look like this: 226 | 227 |  228 | 229 | The owner might accept your request and merge the commits, discuss it and perhaps ask for some changes to the commits, or decline to accept it. You can monitor how up-to-date your fork is by checking out the status bar right above the files: 230 | 231 |  232 | 233 | Now you're ready to take on a new challenge, either by finding a [Code for DC project](codefordc.org/projects) to work on, or by creating a new project to add to that list. Happy hacking! 234 | --------------------------------------------------------------------------------