Part 3: Feature Development

Assuming you correctly set up your repositories (remote and local), you are now ready to try some feature development!

For this workshop, we're going to start with something simple: writing an event post. If you go to the WiCS website, you'll see that we make posts for all of our events. To try your hand at making changes and committing to a git repository, you're going to write up a post for an event you would like to see WiCS run. This can be anything at any place so feel free to get creative! And if it's something cool and viable, we might even end up running it. Take a little time to come up with some ideas, times and places for your event. Then go ahead with the following steps:

Updating your Repository

Any time you start working on a new feature for a public git repository, you want to make sure that your local and remote forks of the repo are up to date with the public one. That way you are all synced up when you start making the changes. To do this, use the following commands (note that the "# Note ..." parts denote comments and are not part of the commands you'll run):

git checkout master         # Check out your master branch
git fetch upstream          # Fetch any new upstream code
git rebase upstream/master  # Rebase your master branch to match upstream
git push origin master      # Update your remote `origin` repository

Making a New Branch

Like I mentioned in the Intro to Git page, it's good practice to make a new branch before starting on a new feature (Insert Anna's coop horror story here). To do this just run the following command:

git checkout -b "name-of-feature"

This will create a new branch called "name-of-feature" and will switch to using that branch as where you're working right now. In this case, you can just put the name of your event as the branch name.

Note that the single command above is shorthand for the following two commands:

git branch "name-of-feature"
git checkout "name-of-feature"

You may use either.

Writing up an Event Post

A great thing about working on an open source git repository, is that you have access to all the code written by anyone else in that repo. This is super helpful for when you need to learn about the conventions used in that repository during feature development.

For example, on the WiCS website, all of our event posts follow a very specific naming convention and outline, and they are all written in Markdown, a markup language that can be used to generate HTML. While writing your event post, you may find this Markdown cheat sheet useful. To learn how to format your event post, find one of the past posts and review it. (Hint: try cd content/W2016) Note that the README.md file contains detailed instructions to help you out!

Once you have reviewed our naming and formatting conventions, you can go ahead and create the file:

touch "name-of-file.md"   # Creates an empty file named "name-of-file.md" if it doesn't exist

Open the file you just created in your text editor and write up your post!

Adding and Committing your Changes

Once you are happy with your file, you can add and commit your changes to the repository. First, tell git to track the file:

git add filename

Always add specific files. Doing things like git add * or git add --all may accidentally include some messy files you don't want.

Now we'll commit the new file:

git commit -m "A commit message"

There are some conventions we follow for commit messages. Here is some great advice from Elana Hashman about it:

• Use present-tense, imperative commit messages.
  • DON'T write "This fixes issue #234 by optimizing the algorithm"
  • DO write "Optimizes algorithm; fixes #234"
• Write descriptive commit messages that give the reviewer the big picture
  • DON'T write "Updates in css files"; this is redundant and can be determined by viewing the files the patch modifies
  • DO feel free to write multi-line commit messages; keep in mind that while only the first line is visible in summary view, additional comments below go into the git log and can be very useful
• Ask for help if you're not sure how to do some of these things!

Now update your fork's remote repo with the changes you just committed:

git push origin HEAD    # HEAD is shorthand for the most recent commit on the current branch

Once you've completed all these steps, you're ready to submit a pull request, per Part 4: Pull Requests.