Open sourcing your repository:
a roadmap
a personal journey
Intent: help you move to open source
URLs
@theMikeJang
Slides: https://slides.com/mike-1/open-source-and-docs
Blog: https://ai-techwriter.com
Repo: https://github.com/nginx/documentation
Open source notes
@theMikeJang
Presentation built on slides.com
Framework: reveal.js
Blog: https://ai-techwriter.com
Open source does not exclude private discussions
We still have internal documentation repositories
Technical Writer
-
Author (RHCE)
-
Linux Annoyances for Geeks
-
Linux user since 1999
-
Principal Technical Writer, NGINX (F5)
-
I've always tried to contribute
-

CC0
@theMikeJang
https://slides.com/mike-1/open-source-and-docs

Background


Earned a living from OSS
I've open sourced a doc repo before
It's easier if you're 'starting from scratch'
Lesson: Lawyers in tech know OSS
docs.cobalt.io
Result: Creative Commons license
Last year
Key tool: portfolio in a Git repo
Quickie demo: make that repo public
https://gitlab.com/mjang-test-group/mike_jang_qualifications

Audience
- Writers
- Developers
- PMs
- Testers
- Others
Pixabay CC0

https://www.f5.com/products/nginx
Disclaimer
The view expressed on this web site/blog are mine and do not necessarily reflect the views of my employer
Question
Is anyone 100% open source
Minimum: protect PII, security
Others: protect customer info
Others: protect new features until they're "ready"
NGINX and Open Source

NGINX Open Source = 280,049
all other NGINX ~170,000
What? NGINX docs were not open source?
This time last year, I looked for help

Steps to open source
- Management support
- Open source strategy
- Security and Compliance
- The "right" license
- Prepare for Contributors
- The transition
Steps to open source
- Management support
- Docs and open source
- Security and compliance
- The "right" license
- Prepare for contributors
- The transition

Management support
When is it "right" for the business
Our docs serve mostly OSS

Time period = quarter (3 months)
Unique visitors
NGINX (OSS) ~ 280,000
Other NGINX software ~ 170,000
Open source and business objectives
-
Market leader
-
Easier to work with customers
-
Help from the community
-
Talent pipeline

Open source and the community
-
Transactional
-
Here's what you get for contributing
-
The features you want
-
Portfolio building
-
Customers get what they want
-
Potential new job
Value of Open Source

Frank Nagle, Chief Economist, Linux Foundation

Steps to open source
- Management support
- Docs and open source
- Security and compliance
- The "right" license
- Prepare for contributors
- The transition
Docs
Essential to open source
Help with onboarding
Enhances customer retention
One year ago
Docs repo was closed
Corporate committment to open source
Template repository
Docs repo was closed
Corporate committment to open source
Pick the (OSS) license of your choice

Template repository
github.com/nginx/template-repository
Code of Conduct
Source: ContributorCovenant.org
Contributing Guidelines


Steps to open source
- Management support
- Docs and open source
- Security and Compliance
- The "right" license
- Prepare for Contributors
- The transition
Challenges
Personally identifying information
Docs-as-code
Review standards
Personally Identifying Information
Usernames, passwords
Unique domains - RFC 2606
Unique IDs
Auth tokens
Docs-as-code
Markdown with an SSG
Build tools (`make`)
Plugins
May require security evaluation
Review standards (PR/MR)
Code samples
PII
Links
Steps to open source
- Management support
- Docs and open source
- Security and Compliance
- The "right" license
- Prepare for Contributors
- The transition
Stakeholders
Lawyer
Engineering manager
Community lead
License options
Creative Commons
GPL FDL 1.3
Apache 2.0
BSD 2
IANAL
BSD 2
Contributor license agreement
Protect the open source in your software
https://github.com/f5/f5-cla
IANAL
Steps to open source
- Management support
- Docs and open source
- Security and Compliance
- The "right" license
- Prepare for Contributors
- The transition
Contribution guide
Include the community in the SDLC
Show them how to build your software
Include the community in the SDLC
Templates for issues, PRs/MRs
Contributor license agreement
The community and the SDLC
Issues, PRs, MRs, Sprints
Excellent contributors may not know the SDLC
Software development life cycle
Template: Issues and PRs/MRs
https://github.com/nginx/documentation/tree/main/.github/ISSUE_TEMPLATE

How to build your software
Prerequisites (e.g. python, node)
Demo
Build commands. Makefiles.
Good first issue
Minimal knowledge of software
Documentation: "gateway drug"
Software - Quick win issues
Docs - Good first issues
Steps to open source
- Management support
- Docs and open source
- Security and Compliance
- The "right" license
- Prepare for Contributors
- The transition
Protect private commits
Use existing content
Mask commit history
Protect PII, customer info
Process
Rewrite commit history
https://github.com/newren/git-filter-repo
Archive old repository
Create new repo, existing content/commits
Rewrite commit history


Question
Is anyone 100% open source
Minimum: protect PII, security
Others: protect customer info
Others: protect new features until they're "ready"
Protect internal development
Competitive features
Customer-specific
Internal discussions
Internal mirror repository
Steps to open source
- Management support
- Docs and open source
- Security and Compliance
- The "right" license
- Prepare for Contributors
- The transition
Lessons Learned
Steps to open source
- Management support
- Docs and open source
- Security and Compliance
- The "right" license
- Prepare for Contributors
- The transition
Lessons Learned
Steps to open source
- Management support
- Docs and open source
- Security and Compliance
- The "right" license
- Prepare for Contributors
- The transition
Lessons Learned
Template: https://github.com/nginx/template-repository/
Steps to open source
- Management support
- Docs and open source
- Security and Compliance
- The "right" license
- Prepare for Contributors
- The transition
Lessons Learned
- Remove PII
- Audit docs-as-code software
- Set standards for reviews
Steps to open source
- Management support
- Docs and open source
- Security and Compliance
- The "right" license
- Prepare for Contributors
- The transition
Lessons Learned
- Creative Commons 4.0
- GNU FDL 1.3
- Apache 2.0
- BSD 2.0
IANAL
Steps to open source
- Management support
- Docs and open source
- Security and Compliance
- The "right" license
- Prepare for Contributors
- The transition
Lessons Learned
- Contribution guide
- Good first issues
- "Quick wins"
Steps to open source
- Management support
- Docs and open source
- Security and Compliance
- The "right" license
- Prepare for Contributors
- The transition
Lessons Learned
- Old commits: keep private
- Use a mirror internal repo
Open sourcing my portfolio
Merge request: https://gitlab.com/mjang-test-group/mike_jang_qualifications/-/merge_requests/1

URLs
This talk: https://slides.com/mike-1/open-source-and-docs/
Doc repo: https://github.com/nginx/documentation/
Contributor License: https://github.com/f5/f5-cla/
Contributor Covenant: https://www.contributor-covenant.org/
Template: https://github.com/nginx/template-repository/
Quick wins: https://gitlab.com/groups/gitlab-org/-/issues/?label_name=quick%20win
Rewrite commits: https://github.com/newren/git-filter-repo
My portfolio: https://gitlab.com/mjang-test-group/mike_jang_qualifications
Request

NGINX
Community Survey
Expires Sunday August 3 -- 5pm
Questions
LinkedIn: https://www.linkedin.com/in/mijang/
Open Source and Docs
By Mike
Open Source and Docs
- 48