Contribute to the DSpace Development Fund
The newly established DSpace Development Fund supports the development of new features prioritized by DSpace Governance. For a list of planned features see the fund wiki page.
Work in Progress
This page is a work in progress. If you have notes/hints/tips on DSpace development with Git/GitHub, please feel free to suggest their addition, or even add them to this page directly.
DSpace on GitHub
The DSpace GitHub code repository can be found at: https://github.com/DSpace/DSpace
Git Resources
A list of some possibly useful external Git resources:
(Feel free to add to the list)
- Intro to Git for those who know SVN: http://git.or.cz/course/svn.html
- Pro-Git Book (Online) -> Great intro to Git in general
- Git Community Book (Online) -> Another great Git introduction
- Git Reference -> This site is a great reference for various Git commands that are available
- Fedora Developers' list of useful Git Resources
- Fedora Developers' Git Guidelines and Best Practices (not all are Fedora specific)
- Fedora Developers' Git Quick Start Guide
- Chris Wilper's (Fedora Committer) tips/rules on using Git: https://wiki.duraspace.org/display/~cwilper/How+I+Use+Git
Still want to use SVN locally, even though DSpace is on GitHub?
- GitHub does provide some basic SVN client support (e.g. SVN checkout): https://github.com/blog/966-improved-subversion-client-support
- Or, you could obviously download the zipped-up DSpace release packages and import them into your local SVN
Overview of the Git Lifecycle
(Borrowed from Fedora's Git Guidelines and Best Practices)
Git allows a developer to copy a remote subversion repository to a local instance on their workstation, do all their work and commits in that local repository, then push the state of that repository back to a central facility (github).
Bearing in mind that you will always being doing your work and commits locally, a typical session looks like this:
Get a copy of the central storage facility (the repository). This is how you download a copy of the DSpace Source Code (i.e.
[dspace-source]
), but this source code directory also is a valid local git repository. In the below example, we've called this directory "dspace-src", but you can call it whatever you want.git clone git@github.com:DSpace/DSpace.git dspace-src cd dspace-src
- Create a local branch called "DS-123". This is what is traditionally called a "topic" or "feature" branch in Git. You are creating a branch to work on a specific topic or feature (in this case a ticket named "DS-123").
git branch DS-123
- Create a local copy of the branch from master (if it doesn't exist) and make it your active working branch. You are now developing on the
DS-123
branch.git checkout DS-123
- Now, start creating, editing files, testing. When you're ready to commit your changes:
This tells git that the file(s) should be added to the next commit. You'll need to do this on files you modify, also.
git add [file]
- Commit your changes locally. This only modifies your local copy of the repository, and the commits only happen in your local "DS-123" branch.
git commit [file]
- Now, the magic:
This command pushes the current state of your local repository, including all commits, up to github ("origin" repository). Your work becomes part of the history of the public "DS-123" branch on github.
git push origin DS-123
git push
is the command that changes the state of the remote code branch. Nothing you do locally will have any affect outside your workstation until you push
your changes.
git pull
is the command that brings your current local branch up-to-date with the state of the remote branch on github. Use this command when you want to make sure your local branch is all caught up with changes push
'ed to the remote branch.
Some useful Git terms
master: this is the main code branch, equivalent to trunk in Subversion. Branches are generally created off of master. However, it is usually recommended that you not do your work directly in the master branch. Instead, you should look to create new branches frequently (e.g. a new branch for each feature/ticket you are working on), and once that work is completed, merge it back into the master branch. Both branching and merging are much easier in Git, and should become a part of your daily development practices. For more information, see Pro-Git's chapter on "Basic Branching & Merging"
origin: the default remote repository (at GitHub) that all your branches are pull
'ed from and push
'ed to. This is defined when you execute the initial git clone
command. For more information see Pro Git's chapter on "Working with remotes"
unpublished vs. published branches: an unpublished branch is a branch that only exists on your local workstation, in your local repository. Nobody but you know that branch exists. A published branch is one that has been push
'ed up to GitHub, and is available for other developers to checkout and work on.
fast-forward: the process of bringing a branch up-to-date with another branch, by fast-forwarding the commits in one branch onto the other. For more information, see Pro-Git's chapter on "Basic Branching & Merging"
rebase: the process by which you cut off the changes made in your local branch, and graft them onto the end of another branch. For more information, see Pro-Git's chapter on Rebasing and GitHub's 'rebase' page.
Some useful Git Development Guidelines
The DSpace Developers/Committers are still working on our Git Guidelines & Best Practices.
But in the meantime, here's some development guidelines from a few "third parties" (feel free to add additional links)
- Very widely used & popular model: "A successful Git branching model" ('git-flow' branching model)
- There are also "git-flow" tools available at: https://github.com/nvie/gitflow These tools give you quick ways to create the various types of branches described in the above model (release / feature / hotfix branches)
- Chris Wilper's "How I Use Git" (His perspective based slightly off a response to the above "git-flow" model)
- Fedora Developers' Git Guidelines and Best Practices (not all are Fedora specific) - this is how they approach team development in Git
- Hydra Developers' Guidelines for Committers (similar to Fedora's) and Guidelines for Contributors (using Pull Requests)
- Github-flow, which is used within Github. It is similar to the Fedora model, but incorporates code review: http://scottchacon.com/2011/08/31/github-flow.html (Ryan Scherle mentions Dryad is also looking at this model)
Getting Started with DSpace + Git
Clone the repository. (The git repo is ~65MB). In the below example, we named the local directory "dspace-src", but you can name it whatever you want.
git clone git://github.com/DSpace/DSpace.git dspace-src cd dspace-src
At this point, you now have a copy of the DSpace Source Code (i.e. [dspace-source]), and you are checked out to the branch {{master
(master is akin to svn trunk), which will work, but it is the bleeding edge of development and not recommended for production instances.
If you would like to develop on DSpace for your local needs (University, Library, or Institution), you are encouraged to fork this GitHub repository, and commit your changes to your personal/organizational repository. We recommend that you build your repository off of a released "tag" of DSpace such as dspace-1.8.2
. The benefit of being based off of a tag/release-branch is that releases have a series of testing phases to ensure high quality, and there is some maintenance of bug and security fixes.
git checkout dspace-1.8.2
From there, you can follow the standard DSpace build instructions in order to build/install DSpace from the source code. For example:
mvn package cd dspace/target/dspace-[version]-build.dir ant update /etc/init.d/tomcat6 restart
Quick Primer on Using Git
For Additional Help
The following is a very brief intro/primer on various Git commands you may find useful. For more detailed information on various Git commands, we recommend reading one or more of the #Git Resources listed above. Additionally, if you want to read the Git Documentation, you can use git help
command to get more specifics about other git commands.
For example: git help status
would give you the official documentation for the "status" command.
Checking the status of your tree.
git status
Looking at the difference of your work in progress.
git diff
Commit your changes to your local tree.
git commit NameOfFileToCommit.java
Update your tree to get all the changes pushed to this central Git Repository.
git pull
If you would like to update your local checkout, for instance before sending a pull request for your local changes, git rebase
is the tool you will use, e.g.
git rebase master
At this point, if you have any conflicts between your local changes and the latest changes on GitHub, git will prompt you to resolve these conflicts.
If you have any questions contact the DSpace community either on IRC, or on the dspace-devel mailing list.
Contributing Changes/Patches to DSpace via GitHub
While we're still working out the ideal workflow for contributions, existing Committers will have direct push access to the DSpace GitHub repo, while contributors are encouraged to submit a Pull Request for review.
A few notes on creating a proper "Pull Request"
- Please, make sure to create a "Pull Request" from a branch and NOT from your "master". (You'll understand exactly why after reading #2)
- Be warned that any additional changes/commits you make to that branch (before the "Pull Request" is accepted/merged) will immediately be included in that existing "Pull Request". This means that, if you want to continue your local development, you must create that "Pull Request" from a semi-static branch (so that any additional commits you make on "master" in the meantime don't get included as part of the existing "Pull Request").
- The reason why this occurs is that a "Pull Request" just points at a specific "branch" (the branch it was initialized from). It does NOT point at a specific set of commits. So, when the "Pull Request" is accepted/merged, you are pulling in the latest version of that "branch". For more information, closely read the GitHub help page on Pull Requests, specifically noting the following statement:
Pull requests can be sent from any branch or commit but it's recommended that a topic branch be used so that follow-up commits can be pushed to update the pull request if necessary.
- The reason why this occurs is that a "Pull Request" just points at a specific "branch" (the branch it was initialized from). It does NOT point at a specific set of commits. So, when the "Pull Request" is accepted/merged, you are pulling in the latest version of that "branch". For more information, closely read the GitHub help page on Pull Requests, specifically noting the following statement:
- Once your "Pull Request" is created, you can use the GitHub Pull Request tools to communicate with the Committer who is assigned to the Pull Request. If further changes are requested, you can make those changes on the branch where you initiated the Pull Request (and those changes will automatically become part of the Pull Request, as described above)