Getting involved as an Open Source maintainer
New Project or Contribute elsewhere?
It's worth looking around to see if what you're trying to solve would be a fit for another project. Alternatively it could a be niche or new subject which may require you to found a project. Below are some thinking points to help make an informed decision on what works for you.
What's your motivation?
What are your limitations?
Everyone has limitations. Time is finite and people have different strengths and weaknesses. Be honest with yourself and others. Look after your physical and mental health and avoid burnout.
Managing your process and project via a maturity model
Your aim should be to have a project that is sustainable. The documentation below will detail a lot of things to consider and the more you can structure and automate the more you help yourself and other contributors not get bogged down in manual housekeeping. However taking the time to put processes in place also requires time and there are tradeoffs in up front time and the long term returns. The key is to understand the different considerations and keep a note of the decisions you make on them. This will help drive your understanding and plan your way through a sustainability and maturity model as you progress through the life of the project.
Source Code StoragePersonal Repo vs Organisation Open Source Repository Management Readme * Give credit to others
Conformance \ Branch Policies
TODO: Merge - Squash Commit
Dependabot is now built into github and allows management of external dependency updates for popular packagement management platforms such as NPM and Nuget. It also allows managing updates of github actions.
Using tags on your repository is a good way to help get noticed in search results. Make use of key words such as a product, technology, platform or domain subject (for example FHIR for healthcare messaging or SourceGenerator for Roslyn Source Generators as these are niche areas). Avoid using generic terms such as API, JSON, MVC unless you're specifically solving a problem in that domain (for example you're implementing a middleware for the MVVM\ MVU pattern - though if you are implementing these patterns look around to see if you can assist in the others that exist ☺).
The Project README file
Your readme is the landing page in your repository when a browser hits it. You have 3 audiences that you need to consider.
- Those that want to use the project and just want to get started with consuming it.
- Those that want to build the code but don't have access to the repository.
- Those that want to build the code and have access to the repository.
The distinction between having read and write on the repository is important in terms of getting started and a positive experience. If someone wants to make a change locally while they learn, they may want to be able to commit their changes therefore encouraging them to Fork the repository first gives them a better experience. For maintainers \ contributes you may want to direct them to have specific toolsets enabled or they may need signing certificates installed, it might be more nuanced information that is a step up from casual use of the repository.
A license is an absolute must. Businesses and developers will not use projects where the legal protections are unclear. Choose a license is a great resource for understanding your choices on licenses. It's also worth time to look and understand the views held for and against GPL and Microsoft originating licenses.
Code Of Conduct
Support Policy \ Lifespan
In your readme establish a support policy.
- Will you offer support, or is the software "as is"?
- Will you offer paid support? Having an open source license and paid support are not mutually exclusive, despite what you may be told by some consumers of your project.
- Will you accept requests for help via Github Issues?
- Will you suggest using an alternative site\platform for support?
- If you have dependencies on other packages, platforms or operating systems what is your lifetime support policy?
Dealing with Issues \ Tickets
- Consider templates for the different types of tickets
- Enforcement of tickets not following the templates
- Auto lock old closed items.
Covering costs \ Monetization
Github run a sponsorship program and there are also options such as Open Collab. As previously mentioned the amount of money these tend to generate is not a lot to make a living off. It may cover costs.
Be aware of sponsorship abuse if you list sponsors on your site and\or project. There are some organizations such as Casinos that place sponsorship as a form of advertisement and Page Rank boosting for links into their own domains.
Licensing for open source projects
Another possibility is the coverage of costs of licenses and\or hosting. There are suppliers of development tools and hosting that offer incentives to open source projects. These may be free in return for a logo or mention on your site.
Use free tools, packages, platforms
There are a wealth of tools out there that are free or have a free tier for open source, indie development or low level usage. You can now get a web site \ application hosted in a fashion that allows you to reduce costs on getting started.
Wiki or not to wiki?
Generating Traffic and Raising awareness
Issues \ Bugs workflows on github
Discussions on github
Stack overflow is a community site that can self driving for knowledge can be a good way of having a community help each other and articles are archived by a search engine. Unlike IM platforms they don't require additional tools. When starting out it can be important to keep an eye, as your userbase grows you may find you gain a critical mass and others will keep the knowledge flowing.
Stack overflow can be a toxic and intimidating environment with over zealous, opaque and unaccountable moderation combined with "newbie" intolerant contributors it can be an off-putting experience. Stack Overflow has introduced a code of contact but as of May 2020 it has no visible benefit. I would recommend using an integration with a messaging tool such as Slack to monitor keywords relating to your project. But I would NOT use it as the primary driver of support and knowledge.
One of the uses to consider using Stack Overflow for is to track requests for the problem your product \ project is aiming to solve. Be careful not to have your answer look like advertisements but show how it solves the problem of the question being asked.
Communication tools such as Slack \ Gitter.im
Messaging tools can be a handy platform but take into consideration there is knowledge being captured that can be useful to others in the future and not readily available. Look for a way to extract them automatically, have people update the documentation, or encourage the use of sites like stack overflow.
Architecture Design Reasoning
- Unit Tests
- Sharing configuration across .NET projects with directory.props and directory.targets
- Strong Name Signing * Don't do it (explain the headaches) * Give instructions to Claire Ovotony's self sign tool
- Authenticode Signing
Getting a developer started.
Local development environment
- Script Bootstrapping
- Vanilla MSBuild
- Build Solution
- Package Restore logs
- Build logs
- Treat Warnings as Errors
- Unit Tests
- Code Coverage
- Integration Testing
- In memory test harness
- OWASP ZAP Scanning
- Breaking Change Scanning
- Documentation Generation
- OMD generation
- Enable xmldoc generation
- Use a separate branch or repo for documentation?
- Ship a nuget package
- make the recipient docfx repository depend on the package
- Use a dependency update tool
- run a package restore task
- run a pre build task to extract the nuget package contents
- configure docfx to scan the extracted nuget packages for dll and xml
- Structuring content
- Integration Tests
- Fail Build On Lack of Coverage
- Package Artifacts
- Package signing
- Reviewing packages
- Testing packages
- Machine or PerUser install?
- Out of date depedency analysis
- Dependency License Analysis
- Static Code Analysis
- Technical Debt Monitoring
- Jetbrains duplicate code scanner
Continous Integration* Choosing a build host AppVeyor Github Actions Azure Devops Pipelines * Upload coverage * Deploy documentation
Continous Deployment* Libraries vs Applications * Choosing a deployment toolset * Managing risk
Planning hosting* Planning decomission * Planning rollback \ rollforward fixing * Planning Staging \ Canary deployments * Planning High Availability \ Disaster Recover * Planning deployment
- Entity Framework
- HTTP endpoint available per node
- Healthcheck API call
- Windows service installed + running
Dealing with consumers
- Change requests
- Defining value
Work Items and Pull Requests
Defining exit criteria
Fault Tracking and Performance Monitoring