For any contribution you have in mind, please open a detailed issue on what you are contributing and why. This way, there can be room to have a productive discussion before any code is written. It can be discussed if the contribution is a good fit for this project, fine tune contribution goals, and more.
Feel free to drop into the Civic Tech Index Slack to reach out and ask any questions.
Set up
Before you start working on an issue
After you've worked on your issue and before you make a pull request (PR):
Okay. You're good to go!
-
In the Civic Tech Index Slack channel, post your email address to the project manager and we'll add you to the Google Drive. Once you've been added to the Google Drive, we will send you a link to the roster and request that you add yourself.
-
Once you've added yourself to the roster, we have verified you can edit files in the CTI Google Drive. Please notify the PM.
-
Setup two factor authentication on your account hackforla/admin-governance#20
-
We will add you as a member to the GitHub repository Team. Once you have accepted the GitHub invite (comes via email or in your GitHub notifications), please mark your membership public https://help.github.com/en/articles/publicizing-or-hiding-organization-membership#changing-the-visibility-of-your-organization-membership
This section discusses some tips and best practices for working with Git.
-
Generally changes start on your local clone of this repository, in your own branch.
-
Commit your changes with a comment related to the issue it addresses to your local repository.
-
Push that commit(s) to GitHub.
-
From the
CTI-website-frontendrepository, create a pull request (PR) which asksCTI-website-frontendto merge your changes into the repository. -
After the owner of the
CTI-website-frontendrepository approves and merges your pull request, your changes will be live on the website.
For git beginners, this process will create a copy of the repository on your local desktop.
First create a new folder on your computer that will contain Civic Tech Index projects.
In your shell, navigate there then run the following command:
git clone https://github.com/civictechindex/CTI-website-frontend.gitYou should now have a new folder called CTI-website-frontend.
Note: Instead of working on a clone, you can choose to make edits on a fork. To view the previous instructions on how to do that, look at the version of this document dated Jan 14, 2021.
Docker will soon be the recommended approach to quickly getting started with local development, but this step is optional for now, and most devs are not using Docker.
Docker is a tool that can help create a local/offline version of the CTI-website-frontend website on your computer so you can test out your code before submitting a pull request.
The recommended installation method is Docker Desktop for Windows 10 64-bit and Mac. Linux users may check out Docker Engine instead.
More on using Docker and the concepts of containerization: Docker overview
Ensure you run the docker commands below from a shell inside the local directory containing your clone of this repository.
- Build the image:
docker build -t [image-name] . - Run the image:
docker run -p [port#]:80 [image-name] - Open in browser: "localhost:[port#]"
Example:
docker build -t webmasterimage .
docker run -p 80:80 webmasterimage
In browser go to localhost:80
Create a new branch for each issue you work on. Doing all your work on topic branches leaves the repository's main branch (named main) unmodified.
The git branch command will let you know what branch you are in, and what branch names are already in use.
git branchYou will see a list of all of your branches. There will be a star (*) next to the branch that you are currently in. By default you should start on the main branch.
The git checkout command will create and change to a new branch where you will do the work on your issue. In git, the checkout command lets you navigate between different branches. Using the -b flag you can create a new branch and immediately switch into it.
To create a new issue branch, and switch into it (be sure to customize the branch name to your own):
git checkout -b build-project-card-140The text after the -b, in the example build-project-card-140, will be the name of your new branch. Choose a branch name that relates to the issue you're working on. (No spaces!)
The format should look like the scheme above where the words are a brief description of the issue that will make sense at a glance to someone unfamiliar with the issue.
No law of physics will break if you don't adhere to this scheme, but laws of git will break if you add spaces.
When you've finished working on your issue, follow the steps below to prepare your changes to push to GitHub.
Once you are done with the work on your issue you will push it to GitHub. Before you can push your work, you will stage and commit your changes. These two commands are similar to the save command that you have used to in other programs.
This command prepares your changes before you commit them. You can stage files one at a time using the filename, or many at a time using wildcards, or you can use the . to stage all of the files that you have added or made changes to. For more information on git add, see https://github.com/git-guides/git-add.
To stage changes to a specific file, run the command:
git add path/to/file/you/just/edited.jsTo stage all of the changes in your folder, run the command:
git add .This command will list the files that have been staged. These are the files that will be committed (saved) when you run the next command, git commit.
git statusThis command saves your work, and prepares it to push to GitHub. Use the -m flag to quickly add a message to your commit. Your message should be a short description of the issue you are working. It will be extremely helpful if other people can understand your message, so try to resist the temptation to be overly cryptic.
To commit your changes with a message, run:
git commit -m 'insert message here'We use ESLint and Code Climate to improve code quality. ESLint works on your local machine before you submit your PR, while Code Climate is part of the CI/CD process on GitHub after you submit.
ESLint is included in the repo when you run npm install. We use the eslint and eslint-plugin-react packages. The exact settings can be found in the .eslintrc.json file.
To lint the entire repo, run npm run lint from the command line.
To lint a single file, run npx eslint path/to/file.js
To see if ESLint can automatically fix warnings and errors for you in that file, run npx eslint --fix path/to/file.js
Be sure to lint your code before pushing changes to GitHub. Eliminate errors and warnings before submitting your PR. (If that can't be done for some reason, please explain why in the PR.)
Most editors, including Visual Studio Code, can show the linting errors and warnings to you while you edit. Once you have installed the repo, just make sure you have installed the ESLint Extention as well. (Similar tools exist for most other code editors.)
Code Climate is triggered by submitting a pull request. You don't have to do anything else beyond submitting the PR. ESLint warnings and errors include issues that would flag warnings in Code Climate, so resolving ESlint issues before submitting PRs will frequently avoid Code Climate errors.
Do all your work on topic branches (as suggested above). To push the your branch's changes to GitHub:
git push --set-upstream origin your-branch-nameTip: If you simply type git push instead, the command will fail, but it will also print out the full command above for an easy copy-paste.
Note: If this is your first time pushing after setting up two factor authentication, you may receive an authentication error and need to type in your github credentials. If you are using the command line to push and the credentials you typed in failed, follow this link to see how to create a personal access token to use as the password for your credentials.
Now create a new pull request to ask for your updates to be incorporated into the live web site.
Go to https://github.com/civictechindex/CTI-website-frontend/pulls and click on "New pull request".
Please rename your pull request something descriptive, e.g., "Build a project card".
Review the changes that will be included in the pull request and, if it fixes a specific issue, include Closes #140 in the pull request message so the issue will be closed automatically once your pull request is accepted and merged.
(Actually, you can include a few verbs — "Closes," "Fixes," or "Resolves" — plus the number sign and the issue number. To read more on linking issues and PRs, see "Linking a pull request to an issue using a keyword" in GitHub's docs.)
The Civic Tech Index project is separated into two repositories in GitHub, CTI-website-frontend, the front end built in React, and CTI-website-backend, the back end built in Django and Python.