It has been a little too long since I launched CMAA’s GitHub presence, and since then there has not been as much activity as I would have hoped. We’re all busy people, and I know it isn’t exactly apparent to everyone why or how GitHub (specifically) or an Open Source approach to the creation music and liturgy resources (generally) could be used.
To remedy that, I have created a new project I hope at least some of you will contribute to: The Open Metrical Psalm project.
(Please, please, please, spare us all the negative comments about metrical psalms as a genre.)
Of the infinite number of good ideas available, this has been chosen because it is easy to think about, finite in scope, and doesn’t require understanding or dealing with some of the more complex technologies for Open Source music creation (like Lilypond or Gregorio).
This is a TEXT BASED PROJECT, which I hope will provide a platform for the following:
- Giving non-tech people a way to learn about and interact with GitHub
- Demonstrating the techniques and philosophy of Open Source content creation
- Providing an example of “Open Source as Infrastructure“
- Encouraging ecumenical and inter-association community work
Additionally, if we create something really useful, and have the opportunity to practice our hymn-writing skills, that would be even better.
The rest of this post is about what this whole thing is about and how to contribute. If you have been wondering how to even use git and GitHub, this would be a good thing to dive into (tutorial provided), and if you’re just curious about Open Source content in general, this is also for you.
What is Open Source and Open Content?
Open Source refers to a way of developing software which includes specific methods and also a philosophy or culture. To put it simply, the idea is that the code for an application or tool is
visible, available, copiable, and editable. Along with this way of developing and distributing software is a culture or philosophy that emphasizes collaboration, community, sharing, and continual improvement.
This blog is not the best venue for trying to convince the unconvinced about the virtues of Open Source software, but (try to trust me on this) it has serious advantages. While non-software people (users) tend to have some weird idea that Open Source software is essentially free and crummy versions of commercial “real” software, the reality is that developers and tech people rely on Open Source software for a great deal of their work. The majority of mobile phones in the world run an Open Source operating system, the majority of websites are hosted on machines running Open Source web servers and delivering content stored in Open Source databases. Open Source is the infrastructure that runs the modern internet.
Open Content is the natural development of Open Source, an application of the methods and philosophies of Open Source to the creation of non-software content. Wikipedia is the most obvious example of Open Content creation.
Open Content for Music
Open Content has problems that Open Source does not. While it is fantastic for non-fiction work like an encyclopedia or a users manual, neither the methods nor the philosophy lend themselves easily to the creation of artistic content such as new hymn texts or new music.
However, it seems that compiling a collection of discreet works (a bunch of individual hymn texts) is a task where the benefits of an Open Source approach might shine.
The Open Metrical Psalm Project
The purpose of the Open Metrical Psalm Project is to create a large collection of freely-available hymn texts which are either directly metrical paraphrases of Psalms, or closely inspired by Psalms. The ultimate goal is to have at least one (and, hopefully, several) good metrical paraphrases for each Psalm, for use as hymns in liturgical and devotional practice.
Contributions to the collection can either be existing Public Domain texts, or new texts which the author (copyright holder) has agreed to release into the commons through the Creative Commons license. (I’m hoping that hymn writers will write new texts specifically for this project.)
As I mentioned above, another goal for the project is simply to provide a platform for people to interact with and explore the idea of Open Content creation and using GitHub.
(For more information specifically about the project, see the Open Psalm Project README.)
GitHub
GitHub is a version control system and collaboration platform. A project (or “repo” – repository) is stored at GitHub, and can be easily viewed and edited there.
But they don’t have to be viewed and edited there.
One of the benefits of this idea (unlike using Microsoft Word or Google Docs for this sort of content) is that the contents can be read without special software. They are plain text.
GitHub provides a number of other benefits as well, such as the ability to easily collaborate without having to coordinate or manage who is doing what. (Part of the Open Source ethic is that people work on the aspect or feature they think is important, not the one they are told to work on by a manager.)
How to use GitHub to contribute to the Open Metrical Psalm project
(or any other project, for that matter)
People who are really into this bring the files they are working on to their own computer and edit them there. But that involves an extra layer of setup and is, for projects like this one, not necessary.
So let’s look at how to contribute while editing online, inside of GitHub.
It’s really pretty easy.
For starters, set up a GitHub account.
 |
| If you need more explanation for this, please do not contribute. |
Then, go to the repository for the project you would like to contribute to. In this case, the Open Metrical Psalm Project.
You’ll see all sorts of stuff about the project, including a complete directory and file listing, project statistics, a README file providing basic information about the project, and all sorts of utilities and functions. Try not to get bogged down in all that.
To start getting familiar with the project, read the README. It’s under the the file listing.
Once you’ve read that, you should start to have a better idea of the scope of the project and what type of contributions it might be seeking. After that you should check out the current content. (At the time of this writing, there’s not much, but there’s enough to get a sense of things.)
 |
| If you click the 023 directory link, you’ll find…
|
 |
The directory for Psalm 23 ( /023/ ), with a file for The King of Love My Shepherd Is, a metrical paraphrase of Psalm 23.
Click on that, and you will find… |
Now – you can view the project. How do you edit it if you want to contribute?
Fork – Edit – Pull Request
To simplify a very complicated topic, the general workflow of a GitHub project is:
FORK – Create a “fork” or copy of the repository.
EDIT – Make your desired changes to your copy of the project.
MERGE – Issue a “Pull Request” to the project coordinator, requesting that your changes be pulled into and merged with the “main” project repository.
Side note: It is worth mentioning that each copy has equal footing from a technical standpoint. If you wanted to use your copy as the basis for a whole new project, from which other people fork and edit and so forth, that is perfectly fine. A particular copy is only “Primary” because of group agreement that it is.
Let’s dive into each part of that.
Fork
Making a copy of a repo is called “forking” it. (It’s also sometimes called cloning, but ignore that for awhile.) It’s called forking as a metaphor for a fork in the road. At the moment of the fork, the project diverges into two paths. The two paths might merge back together later, but then again they might not. Developers who use GitHub and git (the underlying software) think about the life of a project in terms of
a series of forking and merging paths progressing over time.
Forking is easy. There’s a button for it:
When you fork the Open Metrical Psalm project, the ENTIRE thing (including all its past version history) will be copied to your GitHub account. Now you own the whole thing and can make changes to it (because it is yours).
Edit
Making changes to existing files is pretty easy. There’s an edit button.
Make sure you read the README file, and look at existing files, to get a sense of the correct format for contributions.
Adding a new file is equally easy (but, I think, not completely intuitive).
When looking at a directory, click the plus button ( + ) above the file listing.
This creates a new file in the current directory. The plus sign will be replaced with a text-entry field for you to put the file name into.
Side note: file name formatting is covered in the README.
If you need to create a new file in a new directory, do the same thing, but type the directory name into the file-name field. When you put a slash ( / ) at the end of the name, it will immediately turn that into a directory name and give you another field for writing the file name.
 |
I typed exactly: 023/
As soon as I hit the slash key, the “023” turned into a directory name and I got a new file name field. |
Remember to read the README about directory naming conventions when you do this.
After that, you just type into the text field. It is exactly as easy as typing an email or a Word Doc. (Easier actually.)
Once you are done editing your file, you need to save and commit the file to the repository.
You do this by naming the commit and pressing the commit button at the bottom of the page.
Side note: Doing it this way collapses and simplifies what would normally be several distinct operations: saving the file, adding it to a future commit, committing a large number of edits all at once. Don’t worry about that now, but if you really get into this stuff, it’ll come up again later.
You can leave the default commit name in place, or add your own instead. Typical practice is to use a present-tense verb that describes what this commit does to the repo, rather than what you did (past tense) to the file.
Merge
Once you have made some changes to the project and want those changes to become part of the main repository, issue a “Pull Request.” This is a request for the owner of the “main” repo (the one you forked from) to “pull” your changes into the main repo and merge them together.
Issuing a pull request is just as easy as anything else. There’s a button for it. Well, there’s a series of buttons.
First, go to the “Pull Requests” tab.
From there, click the button for a new pull request.
This gives you the opportunity to look at what is going to be in your pull request, and edit it if you want to (don’t, for now).
Clicking the Create pull request button then gives you a chance to name the request and add a message if you want to (helpful if it isn’t obvious what you did).
Once you’ve named it and added a message, click the big green button and you are done. An alert will be sent to the project owner, who will review and (probably) merge in your changes.
It seems like a lot of steps when you put a picture up for each one, but it is really quite simple and fast. You can probably imagine why you are not allowed to merge your own changes in whenever you want. (The result would be
chaos.) A pull request allows the project owner to review your proposed changes before they make it into the main repo for public consumption.
Moving Forward
After this, the cycle repeats.
You already have a fork, so you don’t need to do it again. You will want to pull in the current state of the main project before getting too far ahead, so that you get other people’s changes into your own editable copy. (I won’t get into that here – it’s a topic for a whole other tutorial.)
Once you have the upstream changes reflected in your own copy, get back into editing and adding new content and issuing pull requests. Pretty soon you’ll be an expert, and you’ll have contributed to something useful.
Fun, right?
The Big Picture
It’s easy to get bogged down in this stuff.
The two common problems are either getting too excited about the technology (“This will solve all our problems!”) or not giving it enough credit for its potential (“I don’t need all this new fangled stuff.”)
While a lot of the Open Source and Open Content people (including me) get really excited about the philosophical implications about all this, it’s important to realize that none of that is the point.
The point of Open Source and Open Content is to spur on collaboration so that something cool can be created that would otherwise be hard to create, and so that it can be shared in a way that wouldn’t otherwise be possible.
Adopting GitHub for new projects expands the methods we can use for this collaborative work and community building, and provides a wide range of benefits that will help catalyze this kind of content creation (most of which I didn’t even touch on in this article).
While I am excited about creating an Open Metrical Psalter, I’m more excited about the projects that will be created and shared after this one. I’m hopeful that GitHub will become as indispensable as the
Choral Public Domain Library. I look forward to posts on the Musica Sacra Forum that end with “you can find the rest of this in my GitHub repo.”
It’s no big secret that a great deal of the strength of the new liturgical movement (the movement, not the website) has come from the free sharing of resources and spirit of collaboration at the grass roots level. That initial excitement from several years ago seems to have faded a bit, as the movement has either been pushed back in some areas, or become blessedly normalized (but therefore, no longer new and exciting) in others.
Let’s get excited again. Let’s do something new, learn something new. Let’s make a dent.
