Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Successfully Publishing a Tested, Upgradeable and Documented Open Source Library

Successfully Publishing a Tested, Upgradeable and Documented Open Source Library

You’ve written some code, and you’d like to release it as Open Source. Congratulations!

Publishing an Open Source library goes beyond just releasing your code on Github. New users with different use cases means preparing for the unpredictable. How do you ensure your code is safe and efficient? Is your code easy to read? Do you have a plan for upgrades in the future?

This talk will look at best practices and showcase a checklist to follow when writing and publishing an Open Source Library, from the documentation to ensuring your library works as intended and doesn’t break applications using it.

Xavier Gouchet

July 07, 2022
Tweet

More Decks by Xavier Gouchet

Other Decks in Programming

Transcript

  1. 3

  2. Repository statistics - 2400+ commits - 3 developers - 20+

    contributors - (internal and community) - 30 published versions - 10 libraries 6
  3. Ensure the code is safe 10 ▪ objective zero crash

    ▫ Static Analysis ▫ Code review ▫ *-tests ▪ Real life use cases
  4. Static analysis (Detekt) ▪ Forbid throwing exceptions ▪ Forbid specific

    Kotlin syntax ▫ check ▫ require ▫ !! ▪ List all third party methods throwing exceptions 11
  5. Mandatory Code Review ▪ Increase readability ▪ Generate discussion ▫

    Data structure ▫ Design Patterns ▫ Third party libraries 12
  6. Unit/Integration/End-to-end Testing ▪ Strict policy on the coverage ▪ Deal

    with flaky test ASAP ▪ Stay confident in our tests 14
  7. Real life use cases ▪ Dogfooding in our own apps

    ▪ Regular tests using OSS apps ▫ Wikipedia ▫ Reddit client ▫ HackerNews client 15
  8. Respect privacy 16 ▪ Leverage Sandbox storage / Cache ▪

    Add GDPR option ▪ Write doc about Data Collection
  9. Limit library performance impact 18 ▪ Offload heavy computation to

    background threads/workers ▪ Track Memory Leaks
  10. Monitor library overhead 19 ▪ Compute the impact of the

    library on ▫ CPU ▫ Memory ▫ Network ▫ …
  11. Opt-in or opt-out by default 22 ▪ Balance between “it

    works out of the box” and “it doesn’t do anything that I don’t know of” ▪ Onboarding should work in 15 minutes
  12. Every thing can be configured ▪ Allow enabling/disabling individual features

    ▪ Allow tweaking sampling rates, thresholds, … 23
  13. Use sensible defaults 24 ▪ New customers don’t need to

    configure everything right now… ▪ … or ever
  14. Communicate ▪ Log any actionable “issue” ▫ configuration error ▫

    feature misuse ▫ key internal events ▪ Add actions or documentation links in the message ▪ Provide information about what the library is doing 25
  15. Keep track of API surface 27 ▪ Prevent any API

    breaking change ▪ Provide new option but keep the old ones working ▫ with @Deprecated ▫ with a LogCat log ▪ Provide migration guide
  16. Monitor dependencies $ ./gradlew :my-lib:dependencies releaseRuntimeClasspath +- project :my-lib |

    +- org.jetbrains.kotlin:kotlin-stdlib:1.3.61 | +- com.example.something:core-lib:1.2.0 | | \- org.jetbrains.kotlin:kotlin-stdlib:1.3.61 → 1.5.31 (*) 29
  17. Monitor dependencies $ ./gradlew :my-lib:dependencies releaseRuntimeClasspath +- project :my-lib |

    +- org.jetbrains.kotlin:kotlin-stdlib:1.5.31 | +- com.example.something:core-lib:1.2.0 | | \- org.jetbrains.kotlin:kotlin-stdlib:1.3.61 → 1.5.31 (*) 30
  18. Kotlin Opt-in annotations 32 @RequiresOptIn(message = "This API is experimental.")

    @Retention(AnnotationRetention.BINARY) @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION) annotation class MyCustomOptIn
  19. Why an Open Source Library 36 ▪ It lives within

    our customer’s code ▫ Readable ▫ Editable ▪ Allows direct contribution ▪ Keeps the engineering team closer to our users ▪ We also use Open Source every day
  20. Contributing.md 37 ▪ Developer environment (IDE, tools, …) ▪ How

    to build and run the code ▪ How to run the tests / static analysis ▪ How to contribute ▫ Issues ▫ PRs ▪ Coding conventions
  21. PR & Issue templates 38 ▪ Dedicated files ▫ .github/ISSUE_TEMPLATE/bug.md

    ▫ .github/PULL_REQUEST_TEMPLATE.md ▪ Custom checklist for everyone
  22. LICENSE 39 ▪ Use an existing license ▫ https://choosealicense.com/ ▪

    Apache / MIT ▫ Compatible with your dependencies
  23. build.gradle[.kts] 42 android { minSDK = 19 targetSdk = 31

    defaultConfig { aarMetadata { minCompileSdk = 29 } } }
  24. Keep an Open Mindset 47 ▪ Every mistake is a

    lesson ▪ Look at other Open Source Libraries ▫ http://github.com/Datadog/dd-sdk-android
  25. CREDITS Special thanks to all the people who made and

    released these awesome resources for free: ▪ Presentation template by SlidesCarnival ▪ Photographs by Unsplash 49