Skip to content

Contributing

Jump to bottom
Daniel Reeves edited this page Aug 19, 2020 · 10 revisions

We appreciate that you want to contribute to the Flagging project! There are various ways to contribute to the project, outlined in this document.

The vast majority of contributions to the Flagging site will be code contributions. If you would like to contribute to the Safe Water Project in general, which has more coding and non-coding opportunities to contribute, say hi in our Slack, join our Tuesday meetings, and talk to one of the Safe Water Project's coordinators at the meetings.

What to Contribute

Please utilize the GitHub Issues tab to find a task you want to do. Please comment on an issue to indicate you are working on it.

Read the wiki page about our goals to get an idea of what our trajectory is.

If you do not see something on the Github issues tab, but you do see it in the goals section, or you've discussed an issue with me, or even if you haven't and want to open an issue regardless, do so!

We have a "2 week rule." What this means is if you have an issue checked out, and we do not hear from you for 2 consecutive weeks, the issue is assumed open. To note: you are allowed to disappear for weeks at a time! We simply appreciate you being with us, and encourage you to work on a schedule that's flexible. 😊 We just need to strike a balance between avoiding stepping on toes (by allowing you to reserve an issue) and being agile (by letting others take issues based on priority if the issue is not being worked on). If you have not showed up for two weeks but would like to continue to work on a particular issue, please let a project leader know. Otherwise, assume that when you return you'll be working on a different issue than what you checked out.

How to Contribute Code

Our project follows a standard Git workflow.

If this is your first time working on a collaborative project with Git, check out this handy First Contributions guide.

The basic outline for making contributions is:

Setting Up (First Time)

  1. Fork the project to your Github: https://github.com/codeforboston/flagging/fork

  2. Clone the fork to your computer and add the upstream repo as a remote:

git clone https://github.com/<YOUR-USERNAME>/flagging.git
cd flagging
git remote add upstream https://github.com/codeforboston/flagging.git

Writing Code and Submitting It

  1. Checkout a branch other than master, such as dev or dev_<THING-YOU'RE-WORKING-ON>. git checkout -b <my-branch-name> simultaneously creates a new branch and checks that one out.

  2. Make your changes! 😃 Make sure your code adheres to the Code Style Guide.

  3. Add the the document(s) you added/changed (git add <MY/DOC/PATH/HERE>) and then commit those changes (git commit -m "<DESCRIBE WHAT YOU DID>"), then push those changes.

  4. On your Github fork, submit a pull request ("PR") to the Code for Boston repo. Describe what you did in your PR (doesn't need to be too detailed). If your PR is related to an issue, tag that Issue number in the PR like this: e.g. #6.

  5. If a project manager doesn't get to it in 24 hours, you can ping someone on the Slack channel to review your PR. If there are some changes we'd like first before we can merge it in, I'll discuss with you in the PR comments. If it is good and ready for the code base, then a project manager will say "LGTM" (stands for "looks good to me") and pull it in.

  6. Take a moment to celebrate! 😃 Your code is in the code base, where it will become a valuable contribution to the Charles River Watershed Association.

Post-Submission

  1. On the Monday night prior to our Tuesday meeting, I (the project manager) will try to have my own PR ready that merges everyone's changes to the master branch and makes it even with dev, possibly with a few other changes. I will leave that PR open to comment.

  2. At the start of our meeting, I will ask if anyone has any objections or concerns in merging the PR. If there are no objections or concerns, I will merge it.

  3. Once I accept the big merge to master PR on Tuesday night, run the following:

git fetch upstream
git pull

If you run into any issues running the above, git stash or git reset --hard (depending on what you want to do) and try again.

Development Advice

I strongly recommend using a full-featured integrated development environment (IDE) for work on this project, as you'll likely want to have multiple terminals and py files open simultaneously. PyCharm and Visual Studio Code are two very good IDEs that work well to accommodate a web development workflow. The project managers have experience with these two IDEs and can assist with some basic things in them.

My advice for picking an IDE is: If you are a Python enthusiast, use PyCharm. If you are the kind of person who likes to code in multiple langauges, use Visual Studio Code instead.

I think the only downside to these two IDEs are: (1) if you are new to Python/coding, they can be overwhelming (Atom is my suggested IDE for beginner friendly development); and (2) PyCharm especially but to some extent VSC as well are both very resource intensive.

Clone this wiki locally