-
Notifications
You must be signed in to change notification settings - Fork 353
Contributing
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:
- Fork the project on GitHub (click the Fork button )
- Clone your fork locally (
$ git clone --recursive git@github.com: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)
- Sign the Individual Contributor Agreement
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 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.
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.
Run a clone command against your GitHub fork (substituting your GitHub account name for “you”):
$ git clone --recursive git@github.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
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
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”.
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 <filename>
$ 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.
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.
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.
In order to protect both parties, we ask that you sign the Individual Contributor Agreement prior to us merging your pull request.
Note that you only need to sign the agreement once. There is no need to sign it for every pull request.
Also note that if you are contributing to Spring Social in the form of an extension project that you will maintain, there is no need to sign the agreement. For example, if you contribute to Spring Social Core or Spring Social’s Facebook, Twitter, LinkedIn, TripIt, or GitHub modules, then you must sign the agreement. If, however, you are creating a new module and that module will remain your project, then you are not required to sign the agreement.