3. Collaborative Work & Agile Development

Overview of collaborative work on open source software

Many open source, collaborative software projects adopt a strategy for working together in an enriching, productive space where all people of any skill level are welcome. GeoBlacklight has adopted a version of the Contributor Code of Conduct that sets norms on how to communicate. Similarly, collaborative projects often include a list of instructions or guidelines on how to contribute code and ideas. GeoBlacklight's Guide helps those who many not be familiar with the project identify issues, request changes, and submit fixes in a way that fits within the community's established workflow.

Agile development norms

We won't have time in this workshop to cover all norms for collaborative software development projects. You may want to look at Jono Bacon's The Art of Community and chapter 3, "Communicating Clearly," in particular. Reading this chapter will help you understand the logic of collaborative development. Because work on shared code is often detailed, it's important to have a system of communication in place that minimizes the chance of accidentally "stepping on toes," or taking on a work project that someone else has started already.

Working with Git and GitHub Issues

GitHub has an elaborate set of features that allow teams to parcel out work, request feature changes, report bugs, and set development priorities. Again, we won't have time to go over the entire function of Git and GitHub completely. For now, we recommend reading the Pro Git Book for an overview.

What to do if mistakes are made locally

It is often the case that developers introduce typographical errors, or bugs within their code which prevent the application from behaving as expected. Git provides a set of features which permit you to determine which files have been added or removed, and how each line has been edited.

Correcting Changes (Which Have Not Been Committed)

For cases where Git commits have not been made for the most recent changes, one is able to view the active changes using the following:

$ git diff

This will display the changes in files within the current git repository. For example, if one modified a line within the Gemfile:

$ git diff
diff --git a/Gemfile b/Gemfile
index b53ae51..6a949f5 100644
--- a/Gemfile
+++ b/Gemfile
@@ -73,3 +73,4 @@ gem 'twitter-typeahead-rails', '0.11.1.pre.corejavascript'
 gem 'jquery-rails'
 gem 'devise'
 gem 'devise-guests', '~> 0.6'
+gem 'rubocop'

The +++ is used to indicate the lines which have been added to the Gemfile.

One is able to stash this change with the following:

$ git stash
Saved working directory and index state WIP on master: 2ab1aef Downgrade gems

Now the changes are no longer present:

$ git diff

In order to view the sets of changes available in the stash, please invoke the following:

$ git stash list
stash@{0}: WIP on master: 2ab1aef Downgrade gems

One can apply the last stashed set of changed with the following:

$ git stash pop
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   Gemfile

no changes added to commit (use "git add" and/or "git commit -a")
Dropped refs/stash@{0} (7223048381923c7c9cd6d8c93993a2a79dccdc05)

The stash consists of sets of changes which are stored in a stack. This ensures that the last sets of changes stashed are the first to be retrieved (Last In, First Out [LIFO]).

Correcting Committed Changes

It is also common for one to have invoked a git commit for changes which introduced bugs or other errors which need to be reverted. Git provides a feature for this as well.

Assuming that we committed the previous changes with the following:

$ git commit -m'Adding the rubocop Gem to my Gemfile'
[ignore-this-branch 36de839] Adding the rubocop Gem to my Gemfile
 1 file changed, 1 insertion(+)

We can now view the last 2 committed changes for our Git repositories:

$ git log -2
commit 118d01b20d4450e72a3b7d1ed699cc06fe99f126 (HEAD -> ignore-this-branch)
Author: GriffinJ <[email protected]>
Date:   Thu Jan 30 15:46:20 2020 -0500

    Adding the rubocop Gem to my Gemfile

commit 2ab1aef1fa8f818669f5fa933a1369f59e6dc9e7 (origin/master, origin/HEAD, master)
Author: Eliot Jordan <[email protected]>
Date:   Thu Jan 30 13:05:50 2020 -0600

    Downgrade gems

In order to remove the last committed set of changes from the Git repository, we can invoke git reset. This is done with the following syntax:

$ git reset --soft HEAD~1

Here --soft ensures that Git preserves the changes we've introduced in the committed changes we are removing. HEAD~1 ensures that we are removing one commit from the latest set of commits. If we wished to remove the last two commits, we would use HEAD~2 in place of this.

Now one can see that the file still has our changes from before, but that the commit has now been removed from the history of the repository:

$ git status
On branch ignore-this-branch
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        modified:   Gemfile

Workshop takeaways

Here's a list of best practices that apply to developing on the GeoBlacklight project.

• When identifying bugs, issues, or requests, use the issue template and provide as much information and description as possible. Doing so, even if it seems excessive, helps others in the community replicate the bug or understand what issue is being raised.
• Add appropriate labels to the issues, which helps the community understand the nature of the work and organize tasks.
• Upon starting work on an issue, create a branch of the repository and name it so that it corresponds clearly with the issue it is addressing. If you think you'll need to submit the branch as a work in progress, it's a good idea to use wip as a prefix.
• When making a commit, use a short message that summarizes the nature of the work being done.
• When submitting a pull request, request that someone else on the team reviews your work. Describe in the pull request the specific issue (or issues) being addressed.
• In general, it is considered poor form to merge your own pull request into the master branch of the project.