Setup Help

This document covers some of the issues associated with first-time development environment setup and with collaboration using Git.

Git and GitHub

Installing Git

Please refer to the installation guide according to your operating system to install Git.

Git 101

For a primer on Git for first-time users, see the try.github.io or watch the following video on how to (1) find an issue, (2) fork the code, (3) edit code, (4) open a pull request.

Once you have forked the code and have begun contribution, syncing your fork periodically with the main City Bureau repository will be useful in staying up-to-date with the project.

\1. You must first add a remote link from which Git can track the main City Bureau project. The remote URL is <https://github.com/City-Bureau/city-scrapers.git>. Conventionally we name this remote source upstream. The remote source for your original cloned repository is usually named origin.

$ git remote add upstream https://github.com/City-Bureau/city-scrapers.git

You can see your existing remotes as well by running git remote -v.

\2. Once you’ve added the City Bureau remote, fetch the changes from upstream

$ git fetch upstream

\3. Make sure you are in the branch you hope to merge changes into (typically your master branch), then merge the changes in from the upstream/master branch.

$ git checkout master
$ git merge upstream/master

\4. The final step is to update your fork on Github with the changes from the original repository by running git push.

Creating a GitHub account

If you do not have an account already, go to GitHub and sign up for an account.

Python and Pipenv

Installing Python

Here are some helpful links for setting up Python on your computer:

Installing and using Pipenv

Pipenv is package management tool for Python which combines managing dependencies and virtual environments. It’s also designed to be compatible with Windows. Other tools like virtualenv and virtualenv-wrapper can be used, but our documentation will only refer to Pipenv since it’s quickly being adopted as the standard for Python dependency management.

You can see installation instructions for Pipenv in the Installing Pipenv section of the documentation.

Configuring your code editor

Most text editors can be configured to fix code style issues for you based off of the configuration settings in setup.cfg. Here’s an example for VSCode using the standard Python extension (which can be modified/added at .vscode/settings.json in your project directory):

{
  "python.pythonPath": "${workspaceFolder}/.venv/bin/python",
  "python.linting.pylintEnabled": false,
  "python.linting.flake8Enabled": true,
  "python.envFile": "${workspaceRoot}/.env",
  "python.linting.flake8Args": ["--config", "${workspaceRoot}/setup.cfg"],
  "python.formatting.provider": "black",
  "python.formatting.blackPath": "${workspaceFolder}/.venv/bin/black",
  "python.formatting.blackArgs": [
    "--fast"
  ],
  "python.sortImports.path": "${workspaceRoot}/.venv/bin/isort",
  "python.sortImports.args": [
    "--settings-path=${workspaceFolder}/setup.cfg"
  ],
  "[python]": {
    "editor.codeActionsOnSave": {
      "source.organizeImports": true
    }
  },
  "editor.formatOnSave": true,
  "editor.rulers": [100]
}

This configuration will run linting and style checks for you, and also make necessary changes automatically any time you save. Packages are available for Atom and Sublime Text as well.

Updated: