Page History

...

1. Fork the DSpace GitHub Repo to store your local changes: As GitHub describes in their "Fork a Repo" guide, forking lets you create your own personal copy of the codebase. It not only provides you a place to put your local customizations. It also provides an easier way to contribute your work back to the DSpace community (via a GitHub Pull Request as described in the "#Contributing Changes/Patches to DSpace via GitHub" section below).
   
   • You can fork the repository directly from the GitHub User Interface. Just create an account at GitHub. Then browse to the DSpace GitHub repository (https://github.com/DSpace/DSpace) and click the "Fork" button at the top of the page. This creates a full copy of that repository under your GitHub account (e.g. https://github.com/\[your-username\]/DSpace)

2. Clone your GitHub Repo to your local machine. Now that you have a fork of the DSpace GitHub repository, you'll want to "clone" your repository to your local machine (so that you can commit to it, etc.). You can clone it to whatever directory you wish. You can click the clone button in the Github web interface, or you can use the following command line instruction. In the below example we call the directory "dspace-src". For this to work, you need to setup an ssh key with Github first:

   Code Block
   git clone git@github.com:[your-username]/DSpace.git dspace-src cd dspace-src

   You now have the full DSpace source code, and it's also in a locally cloned git repository!

3. For easier Fetches/Merges, setup an "upstream" repository location. If you have forked the DSpace GitHub repository, then you may want to setup an "upstream" remote that points at the central DSpace GitHub repository. It basically just provides you with an easier to remember "name" for the central DSpace GitHub repository. This is described in more detail in the GitHub "Fork a Repo" guide. That's what the first command below does. The second command adds an easy way for you to check out tracking branches for pull requests simply by running git checkout pr/123. Alternatively, you can check out PRs in the "detached head" state by running git checkout upstream/pr/123. Finally, the third command will download all new references (branch names, tags, ...) from the upstream repo into your local repo.

   Code Block
   git remote add upstream git://github.com/DSpace/DSpace.git git config --add remote.upstream.fetch "+refs/pull/*/head:refs/remotes/upstream/pr/*" git fetch upstream

   (Technically you can name it something other than "upstream". But, "upstream" is just the GitHub recommended naming convention to avoid confusion when using "origin" for your personal fork of "upstream" on GitHub, which you need to submit pull requests to "upstream").

4. Create a branch for each new feature/bug you are working on. Because Git makes branching & merging easy (see Pro-Git's chapter on "Basic Branching & Merging"), you should create new branches frequently (even several times a day) and avoid working directly in the master branch (unless you are making a very minor change). In this case, we'll create a local branch named "DS-123" (note that this branch only exists on your local machine so far). We'll also perform a "checkout" in order to switch over to using this new branch.

   Code Block
   git branch DS-123 git checkout DS-123

5. Do your development work on your new branch, committing changes as you go. Note that at this point, you are only committing changes to your local machine. Nothing new will show up in GitHub yet, until you pushit there. This is a very basic example of a single file commit, but you get the idea.

   Code Block
   git commit NameOfFileToCommit.java

6. Optionally, you can push these changes and this "feature" branch up to your GitHub account. If you want to share your work more publicly, you can push the changes and your new branch up to your personal GitHub repository:

   Code Block
   git push origin DS-123

   In this command "origin" is actually the name of the repository that you initially cloned (from your own personal GitHub account). This pushes your new branch up to GitHub, so that it is publicly available to other developers.

7. Optionally, generate a Pull Request to DSpace GitHub. If this is code you feel should be added to the main DSpace GitHub, you should generate a Pull Request from your "feature branch" (DS-123) that you pushed in the previous step.  This will notify the DSpace Committers that you have a new feature or bug fix which you feel is worth adding to the main DSpace codebase. The Committers will then review this Pull Request and let you know if it can be accepted.
   
   1. For more details on generating a Pull Request for review, see the  Contributing Changes to DSpace via GitHub section below.
   2. Always make sure to generate a Pull Request from a "feature branch" (e.g. branch "DS-123").  You should never generate a Pull Request from your "master" branch.  A Pull Request just points at a branch, so any new commits you add to that branch will be immediately reflected in your previously created Pull Request.

8. Optionally, once you have finished your work, you may wish to merge your changes to your "master" branch. Your personal "master" branch is where all your completed code should eventually be merged ("master" is loosely equivalent to "trunk" in Subversion). So, once you are done with the branch development, you should merge that code back into your "master" branch. Luckily, Git makes this simple and will figure out the best way to merge the code for you. In rare situations you may encounter conflicts which Git will tell you to resolve. For more details, see Pro-Git's chapter on "Basic Branching & Merging". In order to perform the merge, you'll first need to switch over to the "master" branch (the branch you are merging into):

   Code Block
   git checkout master git merge DS-123

   There! You've now merged the changes you made on the "DS-123" branch into your personal "master" branch!

9. Optionally, push this merge up to your GitHub account. Again, at any time, you can push your local changes up to your GitHub account for public sharing. So, if you want to push your newly merged "master" branch, you'd do the following:

   Code Block
   git push origin master

   (I.e. You are pushing your local "master" branch up to the "origin" repository at GitHub. Remember, "origin" refers to the repository you initially cloned, which in this example would be your personal GitHub repo that you cloned in Step #1 above.)

10. Once your branch is no longer needed, you can delete it. Really, there's no need to keep around all these small branches! If you generated a Pull Request from this branch, you will need to keep it around until the Pull Request is either merged or closed. But, once you no longer have any other use for the branch you created, just delete it! Here's an example of deleting the "DS-123" branch from both your local machine and from your public GitHub account (if you shared it there)

    Code Block
    # Remove the branch locally first git branch -d DS-123 # If you have pushed it to GitHub, you can also remove it there by doing a new push (notice the ":") git push origin :DS-123

11. Fetch changes from central DSpace GitHub. New changes/updates/bug fixes happen all the time. So, you want to be able to keep your "fork" up-to-date with the central DSpace GitHub. In this case, you now can take advantage of the "upstream" remote setting that you setup back in Step #2 above. If you recall, in that step, you configured "upstream" to actually point to the central DSpace GitHub repo. So, if there are changes made to the central DSpace GitHub, you can fetch them into your "master" branch as follows:

    Code Block
    # Fetch the changes from the repo you named "upstream" git fetch upstream

    What this command has done is actually create a new "upstream/master" branch (on your local machine) with the latest changes to be merged from that "upstream" repository.

12. Merge changes into your Local repository. Remember, "fetching" changes just brings a copy of those changes down to your local machine. You'll then need to merge those changes into your "master" branch, and optionally push the changes back to your personal public GitHub repository.

    Code Block
    # First, make sure we are on "master" branch git checkout master # Now, merge the changes in the "upstream/master" branch into my "master" branch git merge upstream/master

    In this case, Git will attempt to merge any new changes made in the "upstream" repository into your local "master" branch.

13. Push those merged changes back up to GitHub. Once you are up-to-date, you may now want to push your latest merge back up to your public GitHub repository.

    Code Block
    git push origin master # If the 'fetch' above pulled down new tags/branches, you also may wish to run the following to push those to your own repo. git push origin --all

...