From Zero to Open Source Hero: Contributing to Spring projects

https://www.youtube.com/watch?v=D7OJFWNx-ks

1. From Zero to Open Source Hero Contributing to Spring projects Vedran Pavić @vedran_pavic
2. @spring_io #springio17 Agenda About me What it means to contribute? Why contribute? Where to start? Managing your forks Anatomy of a good Pull Request Lifecycle of a Pull Request Conclusion Q&A
3. @spring_io #springio17 Vedran Pavić • Software Development Engineer at Kapsch CarrierCom d.o.o. • Open Source Software enthusiast – Java, Spring, Linux • Active contributor to multiple Spring projects • Spring Session committer
4. @spring_io #springio17 What it means to contribute?
5. @spring_io #springio17 There’s more to contributing than just code • Helping other users matters – Issue tracker, Gitter, Stack Overflow • Reporting issues matters – stackoverflow.com/help/mcve • Documentation matters - a LOT
6. @spring_io #springio17 What are the prerequisites? • Knowledge of Git, related workflows and GitHub • Willingness to discuss, elaborate and rework your proposals • Contributor License Agreement (CLA) – cla.pivotal.io • Patience :)
7. @spring_io #springio17 Why contribute?
8. @spring_io #springio17 Spring embraces contributions • Move to GitHub made contributing easy • Projects are well managed with contributors in mind – Easy to build & import in IDE • Contributions are properly attributed – Commits, @author tags
9. @spring_io #springio17 Spring embraces contributions • Numbers are also telling:
10. @spring_io #springio17 What do you get out of it? • Learn new skills, improve existing ones – Apply the ideas from Spring projects to your own projects • Meet the people behind Spring and collaborate with them • Grow your reputation • Contributing is an empowering experience
11. @spring_io #springio17 Where to start?
12. @spring_io #springio17 spring.io as service discovery • spring.io/projects contains pointers to all relevant project’s resources – issue tracker, source repository, CI server, Stack Overflow tag
13. @spring_io #springio17 Get familiar with the project • Source repositories contain resources for contributors – README, CONTRIBUTING, CODE_OF_CONDUCT • Note the project’s active branches • Check out the issues marked for contribution – JIRA roadmap, GitHub labels
14. @spring_io #springio17 Get familiar with the project • Project build: Gradle or Maven • Single-click builds that are easy on the newcomers – ./gradlew build or ./mvnw clean install • Check out resources for contributors for more details – Some projects have special build profiles, for example documentation builds
15. @spring_io #springio17 Get familiar with the project • Note the preferred Git workflows – Merge vs rebase • Note the preferred code style – Check source repository for IDE config files • Use other contributions as a reference • Reach out to the project maintainers or community – Gitter or Stack Overflow
16. @spring_io #springio17 Managing your forks
17. @spring_io #springio17 Creating a fork • A fork is a copy of a repository • Serves as a base for contributing activities
18. @spring_io #springio17 Keep your forks lean • Forking creates a copy with all branches of the original repository – Some of them are not active, or not needed • Deleting needless branches makes your fork easier to maintain
19. @spring_io #springio17 Keep your forks up to date • Configure a remote that points to original repository $ git remote add upstream git@github.com:spring-projects/spring-session.git $ git remote -v origin git@github.com:vpavic/spring-session.git (fetch) origin git@github.com:vpavic/spring-session.git (push) upstreamgit@github.com:spring-projects/spring-session.git (fetch) upstreamgit@github.com:spring-projects/spring-session.git (push)
20. @spring_io #springio17 Keep your forks up to date • Fetch and merge the changes from the upstream repository $ git fetch upstream ... From github.com:spring-projects/spring-boot 216506d20f..e236b71615 1.5.x -> upstream/1.5.x 3abd8d3adf..269cea291c master -> upstream/master $ git checkout 1.5.x && git merge upstream/1.5.x && git push $ git checkout master && git merge upstream/master && git push
21. @spring_io #springio17 Keep your forks up to date • Tags need to be handled separately $ git fetch upstream --tags ... From github.com:spring-projects/spring-boot * [new tag] v1.5.3.RELEASE -> v1.5.3.RELEASE $ git push --tags
22. @spring_io #springio17 Clean up your local branches • Clean up after deleting branches on GitHub $ git remote prune origin Pruning origin URL: git@github.com:spring-projects/spring-integration * [pruned] origin/INT-4248 $ git branch -vv | grep gone INT-4248 a2458f78f [origin/INT-4248: gone] Use StringRedisTemplate $ git branch -d INT-4248
23. @spring_io #springio17 Add new upstream branches • As development of the upstream goes on, new branches $ git checkout --track upstream/4.2.x $ git branch -vv | grep upstream * 4.2.x f166bd1bd [upstream/4.2.x] Groovy test: Fix format for `MM` instead of `mm` $ git push --set-upstream origin/4.2.x
24. @spring_io #springio17 Anatomy of a good Pull Request
25. @spring_io #springio17 Before you start • If the issue ticket exists, drop a note you’re working on it – To help prevent duplicating efforts • Otherwise new issue might be needed • Pick the appropriate target branch – Semantic versioning matters - semver.org • If in doubt about target branch consult the maintainers
26. @spring_io #springio17 Working on your changes • Configure your IDE to use appropriate code style – look for Eclipse formatter configuration files – IntelliJ IDEA: Eclipse Code Formatter plugin • Create a dedicated feature branch for your changes - use target branch as base • Initially make your changes a single commit unless there’s a good reason to do otherwise
27. @spring_io #springio17 Tests or it didn’t happen • Unit tests are a must if you touch the code – JUnit, AssertJ, Mockito, Spring Test support • Bug: add a test that reproduces the issue – Check out the contributors resources • New feature: a substantial set of tests is expected – Check the existing unit tests for similar/related functionalities
28. @spring_io #springio17 Write good commit messages xkcd.com/1296
29. @spring_io #springio17 Write good commit messages • There are some excellent resources on writing good commit messages – Check out the contributors resources – chris.beams.io/posts/git-commit • Good commit message does you a favor when opening the PR – Commit message is automatically used for PR description on GitHub
30. @spring_io #springio17 Build project before opening PR • Builds are single-click and easy to run – Check contributor resources for info on additional build profiles, like documentation • Contains additional checks, such as Checkstyle – import the IDE code style config – Use Checkstyle plugin for your IDE • Tests the impact of your changes on entire project
31. @spring_io #springio17 Build project before opening PR xkcd.com/303
32. @spring_io #springio17 Build project before opening PR • sometime build fails for reasons unrelated to your changes – check the project’s source repository and/or CI server for info
33. @spring_io #springio17 Submitting the PR • Remember to select the target branch
34. @spring_io #springio17 Lifecycle a Pull Request
35. @spring_io #springio17 Pull Request checks • Submitting a PR will usually trigger some actions – Contributor License Agreement (CLA) check – PR branch build on Travis CI
36. @spring_io #springio17 Pull Request checks • first time contributors need to sign CLA – cla.pivotal.io has all the details – The process in nearly automatic these days • Minor changes can skip some checks – CLA not required - add “Obvious Fix” to the PR description – Skip the Travis CI build - include “[ci skip]” in commit message
37. @spring_io #springio17 Pull Request checks • Travis CI builds can sometime get stuck or fail for transient reasons – You can trigger the build again by closing and reopening the PR – Or more elegantly using Git $ git commit --amend --no-edit && git push --force
38. @spring_io #springio17 Discussion and reviews • Expect discussion on your proposals, especially if PR is about new features • Often times you’ll be asked to rework your proposal • Don’t open a PR and walk away – If unsure how to rework your proposal ask for help – If you have no time to rework let the maintainers know
39. @spring_io #springio17 Updating your Pull Request • requested changes are done on the existing PR - no need to close existing and open new one • you can simply push more commits to your PR branch • you can update the existing commit (force push is needed) $ git add . && git commit --amend --no-edit && git push --force
40. @spring_io #springio17 Updating your Pull Request • rebase reworked changes on the current state of base branch – remember the tips for managing forks – your PR has been on the shelf for some time
41. @spring_io #springio17 In the end • You didn’t receive response - be patient – It might get some time for maintainers to get to your PR • Your contribution was not accepted - don’t get discouraged – If you’re active in the open source this will happen sooner or later :) • Your contribution was accepted - welcome to the club!
42. @spring_io #springio17 Conclusion
43. @spring_io #springio17 Spring contributions • Spring and entire ecosystem around it wouldn’t be what it is today without contributors • Significant efforts have been made to make Spring projects contributor friendly
44. @spring_io #springio17 The time is right to start contributing • With Spring 5 around the corner there’s a lot of movement across the Spring ecosystem – Move to Java 8 as baseline, introduction of reactive programming model • Most Spring projects are moving to new major release as a consequence – Chance to make significant changes
45. @spring_io #springio17 Q&A
46. @spring_io #springio17 Thanks! @vedran_pavic github.com/vpavic