I have made a couple of diagrams that I hope will give an idea of the process of working locally by a contributor versus a maintainer.
Shared Repository Model
The "Shared Repository" Model is normally used in a GitHub organization
A maintainer does not need to use a fork, because he or she has write permission to the repo
The maintainer can clone the shared repo (using the shared repo URL)
The maintainer can make his or her changes, probably in a branch, and push the changes to the shared repo
The maintainer can create the pull request (directly in the GitHub Organization)
Fork and Pull Model
The "Fork and Pull" Model is normally used in a contributor's account. Because the contributor does not have "write permission" to the GitHub Organization, he or she needs to fork the repo into their user account, where they have "write permission."
The contributor forks the repo
The contributor clones the fork (using the fork URL)
The contributor can make his or her change, then commit the changes to the fork (probably in a branch)
Creating a Pull Request
When ready, the contributor submits the pull request (to the GitHub Organization)
The compare branch should be the contributor's branch
The base branch should be the branch into which the changes should be merged
The contributor creates a pull request title and maybe a description
The contributor clicks on "Create Pull Request"
Reviewing a Pull Request
Now let's switch to the maintainer perspective.
When a contributor creates a pull request, the maintainers of the repo will receive a browser notification or email to inform them that there is a pull request.
Follow the link to the pull request page in the browser.
Review the information about the pull request. You can see the title and description and click on the "Files changed" link to see all the changes made.
Reviewing a Pull Request
Below that will be
A link that says "command line instructions"
A merge button that you can click to merge in the browser, when ready
Pull Request: Command Line
There are some situations when you need to fetch the pull request branch in your local development environment in order to run the code or run a test or work on the code in order to merge it.
When you click on the "command line instructions" link, it will open a set of instructions for how to review and (possibly) merge the pull request in your local development environment.
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
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
Pull Request: Commands
If you need to run the code locally, and you follow the entire instruction set, you will manually merge the pull request branch locally into the branch it is intended to be merged into and push it to that branch on GitHub
I do not do that.
I only follow the part of the instructions to fetch the branch.
I ignore the instructions in red
If I verify that the change can be merged, I go back to the GitHub pull request page in the browser and click merge
For one thing, the main branch is often protected
Also, in the browser, you can simply push a button to revert the pull request
Workflow: GitHub Flow
The workflow we have been using is basically GitHub Flow. It consists of merging pull requests into a 'main' branch.
Workflow: A Variation
Some projects use both main and develop branches.
In this situation, developers merge their work into the dev branch. Eventually, the dev branch is merged into the main branch. If the main branch is deployed, the changes are live.
Some Recommendations
Licenses
Non copyleft licenses
Copyleft licenses
Ethical licenses
GitHub “Choose a License”
A very common license is the MIT license
The MIT License is non-copyleft and gives the user a lot of freedom in the use of the code, including making the code private
A Copyleft License usually requires that the code remains open source
For this reason, copyleft licenses can create a business risk
Ethical licenses (or ethical licenses) are a very interesting subject in my opinion
But sometimes the terms of ethical licenses are difficult to enforce
GitHub has an excellent resource called "Choose a License"
The software supply chain is everything that makes up your code…
Including the GitHub organization, the project, and the people who have access to it
Including the dependencies and external hosting
Therefore, a project needs a security plan with several parts.
Some examples
For the individual level... 2-factor authentication, limited access
For the organization level... scanning of secrets and dependencies for vulnerabilities
For the project level... new releases incorporating the latest security patches and a project security plan with information on how to report vulnerabilities
Open Source Metrics for Evaluating the Health of Your Project
If you want to start measuring your project's health
There are special metrics
CHAOSS, for example, is a collection of metrics that you can use to create a health plan for your project
https://chaoss.community/metrics/
More Useful GitHub Features
A list for future reference of more useful GitHub features
Issue and pull request templates and Global Community Health File Repo
Discoverability: labels/triaging, topics, blog posts
Case Study: DjangoCon US Website
A case study: DjangoCon US Website
Key Points
DjangoCon US Website has been
An opportunity to
Learn the fundamentals of maintaining
Grow a community of contributors
DjangoCon US: The Conference with a Heart
I spent a lot of time looking through GitHub
I realized that many conferences are looking for volunteers who can maintain their web sites
So, I got involved with DjangoCon US
This is a picture of me with some of the other organizers
The Sites I’ve Overseen
I wanted to take my GitHub knowledge to the next level by learning how to be a maintainer
So, I asked the DjangoCon US Chair if I could be a maintainer of the website
She said “sure” and invited me to be the Website Chair, which I accepted
“Low Hanging Fruit” PRs
One of the strategies that helped me learn the process of maintaining
The other maintainer left the easier pull requests for me
I Learned How To...
I learned how to...
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
Increase in the Number of Contributors
Because a Jekyll website is very easy to use
I was able to learn the basics of being a maintainer
And we were also able to drastically increase the number of contributors
From 23 in 2016
To 65 in 2020
Also Became a Mentor
I created the new contributing docs
I helped some beginners make their first contributions
A Few Lessons Learned from DjangoCon US Website
A few lessons learned from DjangoCon US Website
Psychological Security
It is ideal to learn in an environment of psychological safety
Fortunately for me, I could not have stumbled upon a nicer community
The Mistakes Disappear into the Git History
It’s ok to have a beginner mindset; make mistakes, keep improving
The Beginner Perspective is Valuable
A beginner perspective is valuable
Project veterans may not be able to see the project through the eyes of a beginner
A beginner can improve the project for the next person
Example: create installation docs
Achieving 10x Results
Achieving 10x results
People often talk about the concept of 10x results
It is important to remember some of the skills that create 10x results, do not involve writing code
A few examples
Maintaining the docs
Publicizing the project
Mentoring collaborators
My First Tech Talk
When you learn a new skill, you have the opportunity to teach other people and impact the world
After I learned how to maintain the DjangoCon US website, I created a talk about how to do it
It is one of my goals to help other women be maintainers
I gave the talk called “Get a Jumpstart on Collaboration and Code Review in GitHub” for the first time at DjangoCon US 2017
Case Study: Pinax
A case study: Pinax
Key Points
Pinax has been
An opportunity to:
Maintain a complex Django library
Become a Python package release manager
Learn how to deal with scope creep
I Was Hired by Eldarion to Maintain Pinax
In the fall of 2017, based on my experience as a maintainer at DjangoCon US 2017
I was hired to work on Pinax
Pinax is an open source library of Starter Projects, reusable Django apps and themes for building websites
Pinax Was Born: 2008
A little history about Pinax
When I was hired, it had been about 10 years since the idea of Pinax was born
Django had been open sourced in 2005
In March 2008, at PyCon US in Chicago, some Django enthusiasts started working on Pinax
They were creating Pinax to solve their own problem
How It Began
They found themselves reusing some of the same code patterns while creating websites with Django
So they started to abstract these patterns into reusable Django Starter Projects, applications and themes
They wanted to create a reusable web development library that would make choices and compromises
This library would allow them to focus on the features at the top of the stack
That way, they could go from website idea to realization quickly, rather than reinventing the wheel
How It Began
So what was the state of Pinax when I was hired?
It’s quite common, from the very beginning until now, for people to discover Pinax and say “it’s everything they ever dreamed of”
On this slide is one of the very early tweets about Pinax… someone says “Pinax is every idea I’ve ever had.”
How It Was Going, 80 Projects and Apps
By 2017, Pinax had grown to be a large group of professionally-quality, interdependent Django projects and apps
Including starter projects with Pinax apps pre-installed and a Pinax CLI to install them
And sophisticated testing, packaging, and continuous integration configurations
The Pinax GitHub organization alone has around 80 repos in it
This slide includes many of the more popular ones
How It Was Going, Sustainability Lacking
But… sustainability was lacking
Many of the original authors had moved on
Without a strategy to make Pinax easier to maintain, the maintainers began to suffer burnout.
How It Was Going, GitHub Organization, Global Docs, and Slack
In addition to the GitHub organization
Pinax now had a global docs site and a Pinax Slack channel for community and support
There were also app-specific docs in individual repos
Traditional Django Project
Now, I'm going to talk about GitHub and the local development environment and how Pinax works
In your local dev environment, if you are starting a traditional Django project...
You will need to have Django installed and you would normally be using a virtual environment
Run the django-admin startproject command in the terminal to start a project
The project contains the global settings and other configurations for your site
The project template files populated in the directory come from within the Django package
Traditional Django Apps
You would then run an additional command to add one or more apps to your project
Each app contains a special functionality (for example a blog app for a blog part of your website)
The app template files populated also come from within the Django package
Pinax CLI
With Pinax, you can install Pinax CLI (command line interface)
You can use commands to get info about Pinax (such as a list of starter projects or apps)
Pinax starter projects are basically custom Django projects
They already have some functionality built in and by using them, you do not have to start from scratch using a traditional Django project
The same with Pinax Apps
Pinax CLI
You can also use Pinax CLI to install a Pinax Starter Project instead of the traditional Django project
There is a special Pinax CLI command to do this `pinax start
When the Pinax CLI runs this command
The Pinax CLI uses the same startproject command used to install a traditional Django project
But Django calls it from the Pinax CLI code base
Pinax CLI
The starter project URL is passed in as a parameter
projects.json File
The URL leads to a projects.json file that provides the tar file address in the Pinax Starter Projects repo
Pinax Starter Projects
Pinax Starter Projects are in one repo
Each starter project is in an individual branch
Pinax Apps in Starter Projects
Each starter project contains the relevant Pinax apps, to be installed from PyPI (The Python Package Index)
Pinax Apps Stand Alone
Alternatively, Pinax apps can be used independently of any Pinax starter project
You can find them by searching “pinax” on PyPI
A Typical Release
A typical release
Update the test matrix
Add new features
Implement new best practices
Fix deprecations
Improve documentation
Maintaining Pinax Apps
A few important details about maintaining Pinax Apps
We use GitHub Flow workflow
For semantic versioning
We use CalVer at release-level (year.month)
We use SemVer at application-level (major.minor.patch)
Pinax App Codebases
Each Pinax app codebase lives in a GitHub repo
Professional Level Configs
Each app repo has professional level configurations used to keep the code up-to-date
CircleCI is for continuous integration
setup.py contains packaging configurations
tox is for testing the Python/Django versions matrix
Update the Test Matrix
When we do a release, we update the test matrix to support the latest versions of Python and Django
In my release plan, I document some test matrix boilerplate to copy and paste into the app files
pyenv and tox
The process is that…
I clone the Pinax app repo locally, and create a new branch
I update the test matrix in the branch
There is a tool called pyenv that you can use to install multiple Python global versions locally
When tox is run, it can use these global versions to check the compatibility of the Pinax App code against the new Python/Django versions
When there is an incompatibility, tox will show you the error in red
When all of the tests pass… it will show green at the end
Python/Django Release Notes
While you are troubleshooting to fix these incompatibilities
The Python/Django release notes explain all the changes made to the Python/Django codebase in the release
You can use the release notes to understand what updates to make for compliance
Update SemVer Version and Changelog
When all of the test matrix and other updates have been made
You will want to update the SemVer Version in the setup.py
As well as the versions throughout the setup.py metadata and README
Update the Change Log in the README
These are some of the various pieces of metadata
Tag and Publish
Then go to the “tags” area of the repo
Draft a new release
Include a link to the Changelog
Run a process locally to package the app
I have documented this process in the .github repo in the RELEASE.md file
And publish the package to PyPI (Python Package Index)
20.07 Release
In July 2020, I oversaw the completion of a major Pinax release.
It included approximately 28 applications and notably dropped support for Python 2.7
It was a major milestone for me personally and professionally
I initiated the release, managed the process from start to finish, created the release plan, supervised the work of others, updated 10 applications myself, merged all pull requests, and tagged and published the packages
Some Lessons Learned from Pinax
Some lessons learned from Pinax
Simplified, Self-Service, and Self-Sustaining
I have tried to solve some of the critical problems of Pinax
The goal in general has been to implement changes to make it simpler and self-service
As a result, newcomers, contributors, and maintainers could help themselves
And therefore, create a culture that could sustain itself
Major Improvements I’ve Led
Major improvements I’ve led
Documentation of tribal knowledge
Consolidation of docs, in one easy-to-find place
Standardization of configurations between projects
Creation of detailed release and maintainer docs
Creation of Community Health Files, including Issue and Pull Request Templates
Significant reduction in the number of issues and pull requests in order to get up-to-date with new issues and pull requests
The Importance of Publicity
One of the most important lessons I've learned from Pinax
Sometimes it is counter-intuitive
Sometimes it is important to stop and communicate your progress and plans to the community
And ask for help
For example, because of my blog posts, I received help that was crucial in completing the latest Pinax release
Burnout
There is a real danger of burn out in open source
It is a sad subject
Code authors and maintainers are generous
Sometimes they work too hard
And unfortunately, sometimes they have to deal with the negative attitudes of code users
I'm not sure Pinax is going to be healthy and thrive again
But, I’ve learned a lot from Pinax
I want to talk about some ways to make a self-sustaining community
For the maintainers, contributors, and users
Reduce Scope
Ways to reduce the scope
Mark repos as deprecated
Archive repos
Disable issues
Communicate that the code is maintained sporadically
Additional Automation
You can implement additional automation to reduce the workload
Here are a few places where you can find automation tools
