今日推荐英文原文：《How to Open Source Your Code》
推荐理由：一个中国风的 React UI 组件库，包括卡片，进度条和提示等等。尽管这个组件库的组件种类并不多，但是其风格还是相当有意思，不过要注意的是这个库还在开发中，兴许在开发完成之后会提供更多种类。这个项目是作者在寒假期间所做，当然也从中学到了很多只有实践才能了解到的知识。纸上得来终觉浅，欲知此事须躬行，这句话用在写代码上依然适用。
今日推荐英文原文：《How to Open Source Your Code》作者：Sanjay Nair
How to Open Source Your CodeIn my last post, I outlined what open source is and presented some steps for how to get involved. Every open source project available today, even those with many thousands of contributors, all started with at least one person who had the drive to make what they were creating available for other to freely use and contribute to.
If you fall into this category of people but don’t have a good idea of how to get started, then this is hopefully a good place for you to start. We will cover some of the high level concepts and steps you can take to get your project ready for the world of open source.
While these are my top picks for how to properly prepare a project to be open sourced, this list is by no means exhaustive. The best source for open source is always the community at large. Everything said here is based on my experience participating in open source as well as learning from others maintaining their own projects. After reading, I encourage you to go find one of the many amazing open source projects out there and follow their examples. There are some links at the end to help you get started!
Step 0: Identify the OpportunityThis is more of an optional step but, in my opinion, since open source is all about adding value through collaboration, your first step might be to consider some things about your code.
- Is this something that you got value out of?
- Is this something that you think others would get value out of?
- Do you think more people contributing would improve the quality of what is being provided by the code?
Step 1: Prep the CodeThe baseline requirement for a project to be viable in the open source landscape comes down to the thing that makes open source a concept in the first place: enabling other people to be productive using, modifying, and improving its code. With that obvious requirement, you need to ask yourself a simple question:
If I handed someone this project right now, how hard would it be for them to read the code, run the code, and change the code?
You could follow up on that with:
- Are there any tools that the contributor should install or be familiar with before getting started?
- Does it matter what platform the person is working on (Windows vs Mac vs Linux)?
- How can the person be confident that making a change in one place won’t break something else in the code, i.e are there any tests?
- Is the code well organized and easy to follow?
Step 2: READMEThe README might be the most important document included with a project when it comes to providing a newcomer with the summary of what your project is all about. In addition to a brief summary of what the the code is trying to accomplish, the README is the first place you can answer some of the questions listed above. Someone stumbling on your code should be able to start by going through the README and end by at least being able to understand what the code can do, download it to their machine, and run it.
Try to find some examples of cool README documents from some of the prominent open source projects on Github. As flashy as they are with badges and logos, remember that they all answer the basic questions listed above in some way.
Step 3: The LicenseThe open source license is probably the second most important document you want to include in your project before releasing it out into the wild. In short, since you’re putting your code out there for anyone to see, you probably want to have some control over what people can and can’t do with it once they have it. For example:
- Are you OK with someone using it to run their business?
- Are you OK with someone modifying it and selling it as their own, new product?
- Does the entity using your code need to explicitly give your credit when using any original or modified version of your code?
You can drop in a license right when you create the repo on Github!
Step 4: How to ContributeA set of contributing guidelines is the next important piece of documentation you should include, usually in the form of a CONTRIBUTING document much like the README. The CONTRIBUTING document or set of documents serve to inform the prospective newcomer to your code on how you as a maintainer want them to go about making contributions.
A CONTRIBUTING doc serves to answers some questions like:
- What are some ways I can contribute in the first place? Are you, the maintainer, just looking for bug fixes or new features?
- What’s the first thing I should so when I want to make a change to this code?
- Should I create an issue or just fork and pull request?
- Are there any branching conventions I should follow?
- Should I write my commit messages in a certain way?
- Who are the maintainers aka. who’s in charge here?
- Do you follow any coding styleguides?
You can go as wild as you want with it. Just like the code, all the documentation is also open source, so it can also evolve and improve along with your project! Check out Github’s documentation for some amazing examples of contributing documents in the wild. I particularly like the short and sweet Open Government Contributing guidelines document.
Hello! Thanks for contributing to <Insert Awesome Project Here>
# How to Contribute
Step 1. Please open an Issue with a description of what you're trying to add/fix/change
Step 2. Fork and create a feature branch in the format <some-description>/<your issue number>
Step 3. Please squash all your commits into one with a good commit message before opening a pull request
Step 4. Open a pull request, reference your original issue, and provide a concise description of how your changes fixed the issue
Step 5. Your PR requires 2 approvals from maintainers before it can be merged.
Step 5: CommunityOpen source is at its best when you have a strong community behind it. Whether is just you and a couple of maintainers, or a project that you foresee spanning hundreds of contributors, it’s important to set a precedent for the spirit of collaboration you want to establish around your projects.
While documentation like the README and CONTRIBUTING guidelines could also touch on this subject in some ways, the CODE OF CONDUCT is where you should be most direct about how you expect people to behave and interact with each other.
People might not be explicitly asking the questions that the code of conduct document seeks to answer, but it can always be there to set a baseline standard of conduct if issues were to ever arise. Some of these implicit questions might be:
- Are contributors expected to converse with each other as if they were in a professional setting like an office, or is the tone more informal?
- What are some of the core values someone should adhere to when approaching interpersonal interactions within the community?
- What should someone do if they notice someone behaving inappropriately within the community?
- What, if any action, would be taken if someone were to break the etiquette rules?
Feel free to copy if you find it helpful!
Code of Conduct
- Be kind
- Be welcoming
- Don't be a jerk
But in all seriousness, there are lots of great examples available to reference just like all the other documents. One example is Facebook’s Open Source Code of Conduct which they link to in all of their open source project repos.
Step 6: ConsistencyMaking sure your open source project is successful and productive depends, just like any other project, on you giving it the appropriate amount of time it needs to succeed. This could include simple actions like regularly updating dependencies on major releases, or going through all the open Issues and Pull Requests at least once a week. It’s always better to have someone come across your repo and see commits and merged PR’s that are a few days old rather than a few weeks or months old.
For larger projects with many users and contributors, it might mean making sure you’re being responsive to emails or messages. A common practice among larger open source projects is to have a public instant messaging platform like Slack available for anyone with questions or suggestions to join the community discussion about the project.