Suppose that you’ve been developing with Spring Social and want to work with us to make it better. That’s great! We can’t wait to see what you come up with!
Fortunately, because Spring Social’s source is hosted in GitHub, you’re empowered to work on your changes and then submit them for consideration to be merged into the master branch. Unlike other version control systems where submitting changes involves creating a patch file, with Git you perform your work in your own clone of the repository and then send a request for your work to be merged. Here’s how:
Step-by-step (the short version)
Fork the project on GitHub (click the Fork button )
Clone your fork locally ($ git clone –recursive firstname.lastname@example.org:you/spring-social.git)
cd into your local repository ($ cd spring-social)
Link with the upstream repository ($ git remote add upstream git://github.com/SpringSource/spring-social.git)
Create a branch for your work ($ git checkout -b my-work). Choose a name more appropriate to the work you’re doing than “my-work”.
Develop on your branch (not on master!)
Commit changes to the branch ($ git add . ; git commit -m ‘commit message’)
Sync up with upstream to keep your working copy’s master branch and issue branch up to date: ($ git fetch upstream; git checkout master; git rebase upstream/master; git checkout my-work; git rebase master)
Repeat steps 6-8 until your work is complete
Push your changes to GitHub ($ git push origin my-work)
Send us a pull request on GitHub (click the Pull Request button)
Step-by-step (the long version)
If you’re new to git and GitHub, you may need to do some additional setup to get started. Here’s a more detailed version of the instructions to help you get started with GitHub.
Create an account on GitHub and setup your SSH public key
Create a free account on GitHub and log in.
In order for you to be able to push changes from your machine to GitHub, you’ll need to register an SSH public key with GitHub. Follow GitHub’s setup instructions to create and setup SSH keys.
Fork the Spring Social project repository
When you work on the Spring Social code, you will be working on your own personal copy of the repository by forking the main repository.
To create your own fork of the project go to Spring Social’s GitHub page and click the “Fork” button near the top of the screen.
Clone your GitHub fork to your development machine
Run a clone command against your GitHub fork (substituting your GitHub account name for “you”):
$ git clone –recursive email@example.com:you/spring-social.git
That downloads your copy of Spring Social to a git repository on your development machine.
The —recursive option is important. It tells git to also pull in some custom Gradle build code that’s in a separate project. The build will not work without the build code. If you forget to use the —recursive option, you can manually pull in the build code:
$ git submodule init
$ git submodule update
Change directory into the new spring-social directory. From there you can build the project: $ gradlew build
Create an branch for your work
Before you start working on a new feature or bugfix, create a new branch in your local repository that’s dedicated to that one change. For example, suppose you want to fix a provider sign-in problem. Then you might create a branch named “provider-signin-fix” like this:
$ git checkout -b provider-signin-fix
Keep Your Repository Up to Date
While you work on your changes, changes will accumulate on the Spring Social master that you originally cloned from. So that you can get the latest updates, you’ll need to setup the main Spring Social repository as a remote:
$ git remote add upstream git://github.com/SpringSource/spring-social.git
To verify that the “upstream” remote repository was added…
$ git remote
You should see “upstream” listed there along with “origin”.
Write some code
Edit, build, and test the changes on your development machine. Be sure to write tests for your work!
When your work is ready, commit the changes:
$ git add
$ git commit -m ‘Fixed provider sign-in problem’
You’ll need to use git add for each file that you created or modified. You can also use git add . to add all files, but be careful to not add anything you don’t want shared.
Now you can push your new branch to GitHub:
$ git push origin provider-signin-fix
You should be able to log into your GitHub account, switch to the branch, and see that your changes have been committed. Then click the Pull button to request that your commits get merged into the Spring Social development trunk.
Sync up with the main repository
Every so often as you work on your changes, you should sync up with the main repository to make sure that you’re changes are compatible with the latest state of the Spring Social project:
$ git fetch upstream
$ git checkout master
$ git rebase upstream/master
$ git checkout provider-signin-fix
$ git rebase master
You’ll definitely need to sync up with the main repository before you finish and submit a pull request. But we recommend that you sync up more often, especially if your work involves several files and/or takes a long time to complete. Doing so will minimize the hassle of resolving conflicts.
Should a conflict occur, you’ll need to resolve it. Edit the files in conflict and resolve the differences. The conflicts are clearly marked in the files. Then test the changes and commit them.
Send Spring Social a pull request on github
After pushing your changes to your GitHub repository and once you’re ready to submit your changes to be merged into the Spring Social master, click the “Pull Request” button.
Github will notify us about your change. After we review it, we’ll either merge it into the master or comment on it with suggestions.