Getting Started: Contributing to a Large Open Source Code Base as a Beginner
•Download as PPTX, PDF•
0 likes•14 views
Advice on how to quickly get familiar with a code base and make valuable contributions. Applying modern development techniques to quickly add value to unfamiliar code bases. Considerations of Open Source Community norms.
Recommended
More Related Content
Similar to Getting Started: Contributing to a Large Open Source Code Base as a Beginner
Similar to Getting Started: Contributing to a Large Open Source Code Base as a Beginner (20)
Recently uploaded
Recently uploaded (20)
Getting Started: Contributing to a Large Open Source Code Base as a Beginner
- 1. Getting Started Contributing to a Large Open-Source Code Base as a Beginner
- 2. Rich Dammkoehler 30+ years of professional experience, 40+ years coding Repeat Contributor to FOSS Husband, Father, Nerd, Motorcyclist Vice President of Enterprise Architecture, ConstructConnect
- 3. Choices
- 4. Stability
- 5. Familiarity
- 6. Conformity
- 7. Explore
- 9. Analysis
- 11. Keep It Clean
- 12. Disciplined
- 13. Demonstrable
- 14. Test Driven
- 17. Tooling
- 18. Extras
- 19. Hold the Line
- 20. Technical Debt
- 22. Considerations
- 23. Patience is a Virtue
- 24. Recommended Reading TDD: By Example, Kent Beck TDD for Embedded C, James Grenning Working Effectively With Legacy Code, M. Feathers Code Reading, Diomidis Spinellis Code Quality, Diomidis Spinellis Implementation Patters, Kent Beck Domain Driven Design, Eric Evans Design Patterns, Gamma et. Al. Clean Code: A Handbook of Agile Software Craftsmanship, Robert C. Martin
Editor's Notes
- https://www.inteldig.com/wp-content/uploads/2017/06/open-source.jpg Advice on how to quickly get familiar with a code base and make valuable contributions. Applying modern development techniques to quickly add value to unfamiliar code bases. Considerations of Open Source Community norms.
- https://2.bp.blogspot.com/-aXuDIdk8arM/Uth1zpR5lYI/AAAAAAAAD2I/P0Nvy__wOuE/s1600/choice2.jpg Simple Picking a problem Is the problem you are looking at really a good fit for the code base? Join the community and ask. Maybe there is an open issue that addresses or partially addresses the issue and you can join in Maybe the problem has an alternative solution that you haven’t discovered but the community is aware of Maybe this problem has been discussed and deemed unwanted or unadvisable Sometimes we want a feature in a product but it doesn’t align philosophically with what the product designer sees as the purpose of the product. Before you invest blood, sweat, and tears into a solution, be confident that your idea has merit in the eyes of the community. Sometimes starting a new tool/library/platform is the right answer Leverage forking of repositories to kickstart such efforts Be wary the license rules here and understand that obligation Borrowing For OOS, the Issues list is a great place to start; find an unassigned issue that might be easy to fix and give it a try Remember, you don’t necessarily have to succeed! Keep it small at first You’ll get better/faster feedback if you keep it small You have more learning opportunities if feedback is rapid You’ll get that dopamine hit if you succeed
- https://c.pxhere.com/photos/4c/e0/pebbles_balanced_pebbles_water_balance_rock_nature_stone_stability-1194020.jpg!d Read the LICENSE, README, CONTRIBUTING Guide, and public docs Read the README.md Read the License Is the project still active? Be familiar with the intent of the project/product Are there guidelines you need to follow? Join the community: Discord, Slack, IRC Find out who the community leaders are and where you can get support and ask questions Setup Tooling and Download the code Run the build and tests Don’t stop until it runs clean Use the community for support, don’t go it alone Don’t make changes to the code so it works for you, make changes so your systems work with it
- https://www.bigdataframework.org/wp-content/uploads/2018/05/627.jpg Understand your obligations as a contributor. Understand the legal consequences (esp. As they relate to your employer) Read the Build Script How/when does it ‘compile’ How is the project validated? How/when does it ‘test’? How/when does it ‘analyze’? Are there optional steps? When should those be run? Is there a CI Server? Can you get to the build results? When are builds triggered? Are there special CI Server Only Steps?
- https://i0.wp.com/fabiusmaximus.com/wp-content/uploads/2018/02/I-will-follow-the-rules.png?ssl=1 Read the CONTRIBUTING.md What are the ‘norms’ for making a contribution? How are Pull/Merge requests submitted? What is the ‘normal’ branching style? Do you need to contact the owners before you start a feature/enhancement, or can you just ‘show up’? What special tools might you need (not included in the README)? Is there a code of conduct you need to follow? Are there other style norms that you need to comply with? (Are some of them not automated or automate-able?)
- https://www.gozzys.com/images/Maps/ComplexL1White.jpg Explore Architectural Patterns Figure our what the pattern(s) are? What frameworks are used? If unfamiliar with them, find documentation and tutorials and learn a little about them It might be J2EE/JavaEnterprise; are you familiar with the platform chosen? Tomcat != WebSphere Implementation Patterns Pick a feature you are familiar with, figure out how it’s implemented Pick a second similar feature, figure out how it is implemented Are the implementations similar in architecture and structure? Can you identify the design pattern(s) used?
- http://peswiki.com/images/3/30/MPI_test_bench_600.jpg Testing/Validation How are the system features tested and validated? Tools; standard and common to exotic and homegrown Style; consistent/inconsistent, clean/sloppy Adopt the style of the community Try breaking something to see how the test harness reacts Look at how much coverage is created Look at how coupled the tests are to the implementation (less coupled is ideal) How are tests organized? For each tool/framework employed, how are things associated with the code under test? Does the build stop immediately on failure or keep going to collect all failures? Important because you can be mislead by passing unit tests that fail system or integration tests, you want to know when to run what part of the tests Test Runtime; You want rapid feedback 10s/10m rule If the test suite doesn’t do this, how can can you ‘fake it’ so you get rapid feedback. Develop a strategy for rapid feedback so you don’t get bogged down in 30 minute test runs
- https://i.stack.imgur.com/GsdJM.gif Analysis Tools Are there tools being used to analyze the code base like PMD, CheckStyle, Pylint, JSlint, Valgrind, or Veracode? How/When are they executed? Do they stop the build on warning and/or failure? Ideally Builds pass when there are, No warnings, no errors, and no failures Can you integrate the rules into your tool set to get feedback sooner? Sooner is always better! Is autocorrect available? (E.g. rubocop —fix)
- Custom Image by Foxglove Media; https://foxglovemedia.co/ Start Small, Stay Small Accept that some of the things you are going to do will fail. Failure is feedback and you should embrace it. Failure is not shameful, bad, or wrong, its learning and education. You should be excited when you fail and curious about the cause of your failure. Take a moment to understand why you failed and learn from it. Small Bets make failure hurt less. If you wrote 2 lines of code, ran some tests, and failed... Abandonment Syndrome, sometimes you need to just let go Slow is fast, stay focused on one thing and get it done. It might seem slow, but the stable result makes you faster over time Open Mindedness, your in someone else’s world, be open to their way of doing things, learn from them
- https://www.foodsafety.ca/sites/default/files/2018-09/4_types_of_cleaning_agents.jpg The Boy Scout Rule “Leave the campsite cleaner than you found it” is a rule used by campers; if you camp someplace, clean up after yourself and leave things in a better condition than when you arrived. Apply this rule to codebases; but do so with caution. ‘Better condition’ is related to the rules and standards of a community of people. Learn those rules, and when you find divergence, if it isn’t too disruptive, apply them. There are cases where some code is old and hasn’t been touched since a rule came into place. Applying that rule may be enormously disruptive, so use good judgement Sometimes, applying the rule is the best/right thing, but the timing of that change can have a impact on delivery timeline. It might be better to make that change under a new work item and as a separate effort. Work within the community to evaluate the necessity, value, impact, and timing of such a change.
- Disciplined In any case, green field, brown field, or dumpster fire, you should apply discipline and rigor to your approach Don’t compromise your practices and beliefs for a timeline and don’t concede your position without careful consideration. If you can’t find common ground and agreement, opt out.
- https://live.staticflickr.com/3916/14729909629_b8e9e8f5c1_b.jpg End To End - Make the results of your changes visible as early as possible Demonstrate early and refine often
- http://www.scion.com/scionracing/wp-content/uploads/2013/06/florida-friday-381.jpg Test First - Understanding what success looks like before you begin is essential to success. It tells you if your heading in the right direction and it tells you went to stop TDD is an important microcosm of Test First you should embrace. TDD is a DESIGN Technique Automated Tests are a side-effect Probably the most useful and effective software development practice
- https://farm1.staticflickr.com/167/463202335_fb1766d33c_z.jpg Continuously Integrated - This isn’t about a build server, this is about knowing that the puzzle always fits together. Stay tightly integrated. Regularly pull and or rebase your work to stay current with the rest of the community. If your PR is accepted it will be much easier to merge if everything else is also up-to-date.
- https://live.staticflickr.com/368/19572401032_020ae12a0a.jpg Exploratory - Things might seem ok from your IDE, but they aren’t necessarily ok. Explore the application and make sure it really solves your problem. Do this frequently.
- https://s0.geograph.org.uk/geophotos/05/09/33/5093309_28776acb.jpg Know your tools - The more you know your tools and how to apply them the more likely you are to succeed. Take the time to get really familiar with your tools and what they can and cannot do. When you find gaps between your needs and your tools, look for alternatives, explore your options. Don’t allow your tools to slow yo down or inhibit your creativity and productivity.
- https://live.staticflickr.com/6105/6299254442_5b5b2bb0ec.jpg Strive to implement systems with high cohesion and low coupling. Make an effort to apply techniques that enable easy substitution of parts, isolation of implementation, and clear contracts for integration points. Leverage Domain Driven Design, Hexagonal Architecture, Dependency Injection, and similar techniques. This allows you to adapt designs quickly and take on new challenges and features with a minimum of fuss. Laying this foundation early makes you faster in the long run. It’s an investment.
- https://live.staticflickr.com/87/244870161_2a9468bb74_b.jpg Hold the Line and Raise the Bar Early on, establish a clear definition of acceptable quality. Then hold to that line and don’t accept inferior work. Communication, Training, and Education are essential to maintaining this Everyone needs to understand the ‘Why’ behind these choices State the obvious. It might not be that obvious Raise the bar. Perfect is the enemy of good, but that doesn’t mean we cannot always look for ways to improve. Take time to reflect on quality, speed, and effectiveness. Look for opportunities to improve. Make doing things well the measure of success; not doing things quickly
- https://c1.staticflickr.com/7/6178/6138666188_f86c3cdc67_b.jpg Technical Debt Technical Debt is the difference between what is understood and what is implemented. Technical Debt increases entropy and will eventually stall out progress because the gap is too wide; when the system is incomprehensible, translating features to functioning code becomes very difficult Technical Debt is _not_ a failure to perform maintenance, but we should still do the maintenance.
- https://i.stack.imgur.com/nf6q1.png Comments and Clarity In most cases, for most common languages, comments are not necessary because the code can explain itself. It’s up to you how well your code can express these ideas. Take the time to make sure there is clarity We’ll structured and defined tests can explain more than any comment ever has Behavioral Tests that use Given-When-Then structures can provide a guide not only to what but often to why. Good naming (of everything) provides immediate clarification, don’t skimp on this and be as consistent as possible Method extraction and other structural tactics can lead to more understandable code
- https://images.wired.it/wp-content/uploads/2013/12/Deadpool.jpg Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. — John F. Woods I want to emphasize the necessity of being a good citizen and considering others. It’s important that you put your best effort into what you doing, not just for yourself but for your future self and for the community you working in. Be considerate in how you write code, how well you test, and how thorough and complete your work is. It pays dividends over time.
- https://upload.wikimedia.org/wikipedia/commons/f/fc/Melanoplus_femurrubrum_20070903.jpg Patient Not everything can happen immediately, you must develop patience with yourself and also with the community you work in. Your ideas may be visionary, it will take time to convince others of their merit Your understanding is a function of your curiosity, you must nurture that understanding to make better decisions, this takes time No two community’s operate the same way, you must take the time to learn how to function within the community
- http://luizricardo.org/wordpress/wp-content/upload-files/2016/07/readingbooks.jpg These are not all of the books you could read, but these are all great books! TDD: By Example, Kent Beck TDD for Embedded C, James Grenning Working Effectively With Legacy Code, M. Feathers Code Reading, Diomidis Spinellis Code Quality, Diomidis Spinellis Implementation Patters, Kent Beck Domain Driven Design, Eric Evans Design Patterns, Gamma et. Al. Clean Code: A Handbook of Agile Software Craftsmanship, Robert C. Martin