Maintaining Demystified- DjangoCon US

Transcript

1. Maintaining Demystified By Katherine “Kati” Michel
2. My Affiliations 2
3. Talk Goals • Fundamentals of maintaining • A Case Study: DjangoCon US Website • A Case Study: Pinax • Lessons learned
4. Assumptions You already understand: • The fundamentals of using GitHub • The fundamentals of contributing
5. Get a Jumpstart on Collaboration and Code Review in GitHub
6. Maintaining is Not Just About Code It is also about: • People • Community • Process • Communication • Kindness
7. Put Yourself in the Shoes of the Contributor Make Contributing as Frictionless as Possible
8. GitHub Open Source Guide: “A Checklist Before You Contribute”
9. Some Signs of a Healthy Project • There is a welcoming atmosphere • There is recent activity • The maintainers respond quickly • The maintainers reduce issues/pull requests
10. Ideal Process Prospective contributor: • Finds project • Agrees to Code of Conduct • Reads CONTRIBUTING.md • Uses docs, issue/pull request templates • Submits issue/pull request • Maintainer responds quickly
11. Community Health Files README.md CODE_OF_CONDUCT.md LICENSE CONTRIBUTING.md
12. Documentation • Highly valued • Often overlooked • And a means for establishing inclusive and accessible communities -From GitHub’s 2017 Open Source Survey
13. How Contributors Contribute
14. Shared Repository Model DjangoCon US Website Repo Push branches, submit pull requests Can push or pull because of write permission, no fork necessary Clone Local dev environment
15. Fork and Pull Model DjangoCon US Website Repo Fork Create pull request Push changes, including branches Local dev environment
16. Creating a Pull Request DjangoCon US Website Repo Create a New Pull Request Títle and descriptión Create Choose branches
17. Reviewing a Pull Request Review the changes Títle and descriptión
18. Reviewing a Pull Request Merge button Command line instructions Review the changes Títle and descriptión
19. Pull Request: Command Line
20. Pull Request: Options If You Do Not Run the Code Locally • If no change is needed or the change can be made in the browser • Make the change in the browser • Click merge
21. Pull Request: Options If You Run the Code Locally • If no change is needed, go back to the browser and click merge • If a change is needed, ask the contributor to make the change, or push the update yourself, then click merge
22. Pull Request: Commands Shared Repo Branch Forked Repo Branch $ git fetch origin $ git checkout -b <branch-name> origin/<branch-name> $ git merge main $ git push origin <branch-name> $ git checkout -b <branch-name> main $ git pull https://github.com/<user-name>/<repo-name> <branch-name> $ git push https://github.com/<user-name>/<repo-name> <branch-name>
23. Workflow: GitHub Flow Main Branch Live Production Site Pull Requests
24. Workflow: A Variation Main Branch Live Production Site Pull Requests Staging Site Dev Branch
25. Some Recommendations
26. Licenses • Non copyleft licenses • Copyleft licenses • Ethical licenses • GitHub “Choose a License”
27. Security • Software supply chain • Individual-level (2FA, limited access) • Organization-level (secret and dependency scanning) • Project-level (new releases, security plan)
28. Open Source Metrics for Evaluating the Health of Your Project
29. More Useful GitHub Features • Issue and pull request templates • Global Community Health File Repo • Project Boards, milestones, issues, labels • Wiki, GitHub Pages/Jekyll • Labels/triaging, topics, blog posts
30. Case Study: DjangoCon US Website
31. Key Points An opportunity to: • Learn the fundamentals of maintaining • Grow a community of contributors
32. DjangoCon US: The Conference with a Heart
33. The Sites I’ve Overseen
34. “Low Hanging Fruit” PRs 67 commits, including merging 28 PRs
35. • Fetch a pull request locally • Run the code • Push an update from a fork to a pull request • Merge a pull request locally • Push a pull request to a `main` branch I Learned How To...
36. Increase in the Number of Contributors From 23 in 2016 To 65 in 2020
37. Created contributing docs and helped beginners Also Became a Mentor
38. A Few Lessons Learned from DjangoCon US Website
39. Psychological Safety • It is ideal to learn in an environment of psychological safety
40. The Mistakes Disappear into the Git History • It’s ok to have a beginner mindset; make mistakes, keep improving
41. The Beginner Perspective is Valuable • Project veterans may not be able to see the project through the eyes of a beginner • Improve it for the next person • Example: create installation docs
42. Achieving 10x Results 10x skills that do not involve writing code • Maintaining the docs • Publicizing the project • Mentoring collaborators
43. My First Tech Talk Photo by Adam Gregory of https://atomimages509.wixsite.com/atom
44. Case Study: Pinax
45. Key Points An opportunity to: • Maintain a complex Django library • Become a Python package release manager • Learn how to deal with scope creep
46. I Was Hired by Eldarion to Maintain Pinax Pinax: an open-source library of reusable Django starter projects, apps, and themes for building websites
47. Pinax Was Born: 2008
48. How It Began Personal Sites Inspiring Reusable Features
49. How It Began “Pinax is every idea I’ve ever had.”
50. How It Was Going 80 Projects and Apps account blog static stripe waitinglist zero company documents team-wiki wiki forums socialauth Pinax Themes Popular Pinax Apps Pinax Starter Projects django-user-accounts pinax-stripe pinax-announcements pinax-badges pinax-blog pinax-calendars pinax-cohorts pinax-comments pinax-documents pinax-eventlog pinax-events pinax-forums pinax-images pinax-invitations pinax-likes pinax-messages pinax-news pinax-notifications pinax-points pinax-ratings pinax-referrals pinax-submissions pinax-teams pinax-testimonials pinax-types pinax-waitinglist pinax-webanalytics pinax-wiki pinax-templates pinax-theme-bootstrap
51. How It Was Going Sustainability lacking
52. How It Was Going GitHub Organization, Global Docs, and Slack
53. Traditional Django Project Project Files Terminal $ django-admin startproject mysite .
54. Traditional Django Apps Project and App Files Terminal $ python manage.py startapp myapp
55. Pinax CLI Terminal $ pip install pinax-cli $ pinax projects
56. Pinax CLI `startproject` is called from within the pinax-cli codebase Code Snippet
57. Pinax CLI Code Snippet starter project URL is passed in as a parameter
58. `projects.json` File File Snippet
59. Pinax Starter Projects • Pinax starter projects are in one repo • Each starter project is in an individual branch
60. Pinax Apps in Starter Projects Each starter project contains the relevant Pinax apps, to be installed from PyPI (the Python Package Index)
61. Pinax Apps Stand Alone Alternatively, Pinax apps can be used independently of any Pinax starter project Search “pinax” on PyPI
62. A Typical Release • Update the test matrix • Add new features • Implement new best practices • Fix deprecations • Improve documentation
63. Maintaining Pinax Apps • GitHub Flow workflow • CalVer at release-level (year.month) • SemVer at app-level (major.minor.patch)
64. Pinax App Codebases Each Pinax app lives in a GitHub repo
65. Professional Level Configs tox for testing CircleCI for continuous integration `setup.py` for packaging
66. Update the Test Matrix CircleCI Boilerplate tox Boilerplate
67. pyenv and tox pyenv can be used to install multiple global Python versions Then tox can run the test matrix Terminal
68. Python/Django Release Notes Explain all the changes made to the codebase in the release
69. Update SemVer Version and Changelog
70. Tag and Publish Tagging a release Published to PyPI
71. 20.07 Release • 28 apps included • Support for Python 2.7 dropped • A huge milestone for me personally and professionally
72. Some Lessons Learned from Pinax
73. Simplified, Self-Service, Self-Sustaining
74. Major Improvements I’ve Led • Documentation of tribal knowledge • Consolidation of docs, in one easy-to-find place • Standardization of configurations • Creation of release and maintainer docs • Creation of Community Health Files and Templates • Reduction in the number of issues and pull requests
75. The Importance of Publicity
76. Burnout • There is a real danger of burnout in open source
77. Reduce Scope • Mark repos as deprecated • Archive repos • Disable issues • Communicate that the code is maintained sporadically
78. Additional Automation • GitHub Actions • GitHub Apps • Probot
79. Python Specific Tools • Coverage.py • isort • Black • Restructured Text • And many others
80. Centralize Access and Knowledge • Centralize access • Be willing to hand access over • Avoid solutions that are unique
81. Managing Volunteer Maintainers • Give selective permissions • Protect branches • Require reviews • Use status checks • Revert a pull request, if necessary
82. Final Thoughts
83. When You Get Stuck • Google • Stack Overflow • GitHub docs • Git docs • Atlassian and GitLab docs
84. OS Social Contract “... open source maintainers owe you quite literally nothing when it comes to their open source code, and treating them poorly is unethical.” - Brett Cannon, Python Core Dev
85. Perks of Maintaining • Learn technical skills • Find new professional opportunities • Attend conferences • Meet smart, interesting people • Travel to incredible places
86. Eating Dinner With Guido Me Guido
87. Is it Worth It? Yes :)
88. Is it Worth It? Yes :)
89. Special Thank You :) Thank you to Ricardo Diaz Rincon for reviewing the Spanish version of this talk: Desmitificando el Mantenimiento (scheduled to be broadcast at DjangoCon US 2021 on October 23
90. Contact Me Katherine “Kati” Michel Email: kthrnmichel@gmail.com Twitter handle: @KatiMichel GitHub username: KatherineMichel