开源项目必备的文件

拼搏现实的明天。 2022-10-07 13:53 171阅读 0赞

开源 项目文件 管理

“Open-source” is a buzzword in the technology industry right now. More and more companies are coming into the open-source world, including giants like Microsoft and Google, who are investing heavily in open-source projects with each passing year. Experts have finally realized that it’s not about keeping your code safe from others and trying to make something perfect with the limited resourced you have. Rather, it’s about being collaborative, bringing in more heads than you could ever afford to have, and, in turn, adding more ideas to create a perfect project.

目前，“开源”是技术行业的流行语。 越来越多的公司进入开源世界，包括微软和谷歌这样的巨头，它们每年都在开源项目上投入大量资金。 专家们终于意识到，这并不是要确保您的代码免受他人侵害，并试图利用有限的资源来完善自己的东西。 而是要进行协作，带来比您以往任何时候都多的头脑，并反过来增加更多的想法来创建一个完美的项目。

But the amount of open-source projects that get funding to go ahead is still comparatively low. In recent times, there have been many programs to support the community and bring more people into it thanks to companies like GitHub. Last year, I attended the official launch event of GitHub in my country and one of the main topics discussed was how to encourage this community of creators and contributors.

但是获得资金支持的开源项目数量仍然相对较低。 近年来，由于GitHub之类的公司，有许多计划来支持社区并吸引更多人参与。 去年，我参加了在我国的GitHub的正式发布活动，讨论的主要主题之一是如何鼓励这个创建者和贡献者社区。

In this article, we are going to talk about a few things you need to include in your open-source project to make it easier for everyone — including contributors, moderators, users, and sponsors — to help you in growing the project.

在本文中，我们将讨论您需要在开源项目中包含的一些内容，以使所有人(包括贡献者，主持人，用户和赞助者)都可以轻松地帮助您发展该项目。

# 1.许可证 (1. License) #

Licenses are an important part of open-source projects, as they’re mostly public and free to use. For any open-source repository to stay faithful to its title, it needs to have a license that allows others to freely use, change, or even distribute the project. It’s not mandatory to have a license, but without one, copyright laws will apply to your project. All the rights will stay with you, thereby not allowing people to reuse, recreate, or share your project.

许可证是开源项目的重要组成部分，因为它们大多是公开的并且可以免费使用。 为了使任何开放源代码存储库忠实于其名称，它需要具有许可权，该许可权允许其他人自由使用，更改甚至分发项目。 拥有许可证不是强制性的，但是没有许可证，版权法将适用于您的项目。 所有权利将保留给您，因此不允许人们重复使用，重新创建或共享您的项目。

The best practice while creating a license file is to create a text file named `LICENSE.txt` or `LICENSE.md` in the root of the repository. GitHub officially recommends [Choosealicense][] to understand which license is right for your project.

创建许可证文件的最佳做法是在存储库的根目录中创建一个名为`LICENSE.txt`或`LICENSE.md`的文本文件。 GitHub正式建议[Choicealicense][Choosealicense]来了解哪种许可证适合您的项目。

![Image for post][]

LICENSE on the official Flutter repository. Flutter官方存储库上的许可。

# 2.自述文件 (2. README) #

I know it sounds redundant to add a README to this list, but this is the most important file that every open-source repository should have. A [README][] file plays an important role in introducing and explaining a project. It helps people understand what the project is about, how to run it, documentation, etc. The most common file format used for READMEs is markdown `README.md`.

我知道将自述文件添加到此列表听起来很多余，但这是每个开源存储库都应该拥有的最重要的文件。 [自述][README]文件在介绍和解释项目中起着重要作用。 它可以帮助人们了解项目的含义，如何运行，文档等。用于`README.md`的最常见文件格式是markdown `README.md` 。

Having a great README file can be the difference between getting attention in the ocean of projects out there or not. This [page][] by [Matias][] lists everything you need to write a good README file, including example, tools, badges, etc.

拥有出色的README文件可能是获得项目关注与否之间的区别。 [Matias][]撰写的[本页][page]列出了编写良好README文件所需的一切，包括示例，工具，徽章等。

![Image for post][Image for post 1]

README on the official Flutter repository. 关于Flutter官方存储库的自述文件。

# 3.代码所有者 (3. CodeOwners) #

Regular code review is essential to every successful project, but in many cases, it’s not always clear who needs to review what. By defining a CodeOwners file in the project, repository maintainers can define the people responsible for doing this. According to [GitHub’s docs][GitHub_s docs]:

定期的代码审查对于每个成功的项目都是必不可少的，但是在许多情况下，并不总是清楚谁需要审查什么。 通过在项目中定义CodeOwners文件，存储库维护者可以定义负责此工作的人员。 根据[GitHub的文档][GitHub_s docs] ：

> “Code owners are automatically requested for review when someone opens a pull request that modifies code that they own.”
> 
> “当有人打开修改他们拥有的代码的请求请求时，将自动请求代码所有者进行审查。”

Anyone with admin or owner permissions can create a file named `CODEOWNERS` in the repository’s root directory while keeping in mind that people or teams chosen as code owners must have write permissions for the repository. CodeOwners can be defined for the entire repository or specific file types or folders. For example, if you add code owners for `*.js` files, only people listed on that line will be requested to review.

具有管理员或所有者权限的任何人都可以在存储库的根目录中创建一个名为`CODEOWNERS`的文件，同时请记住，被选为代码所有者的人员或团队必须对该存储库具有写权限。 可以为整个存储库或特定的文件类型或文件夹定义CodeOwner。 例如，如果您为`*.js`文件添加代码所有者，则仅要求该行中列出的人员进行审阅。

![Image for post][Image for post 2]

CODEOWNERS on the official Flutter repository. Flutter官方存储库上的CODEOWNERS。

# 4.贡献 (4. Contributing) #

Open-source projects are all about contributions. That’s how every project grows. For most projects that accept active contributions, it is always good to have a guideline for contributors to make it easier for them as well as reviewers. This file will contain guidelines for anyone who wants to contribute to the project. This can include many things, such as where to find and track issues, sub-projects, blogs for the project to contribute, coding guidelines, etc.

开源项目都是关于贡献的。 这就是每个项目成长的方式。 对于大多数接受积极贡献的项目，最好有一个供参与者使用的指南，以使他们和审阅者更容易。 该文件将包含要为该项目做出贡献的任何人的准则。 这可以包括许多内容，例如在哪里查找和跟踪问题，子项目，为项目贡献的博客，编码准则等。

To add a file, create a file named `CONTRIBUTING`( not case sensitive) with a .md or .txt extension (optional) in the root folder or under `docs/`*.*

要添加文件，请创建一个名为`CONTRIBUTING`的文件  (不区分大小写)，在根文件夹或`docs/`下带有.md或.txt扩展名(可选) *。*

![Image for post][Image for post 3]

CONTRIBUTING on the official React Native repository. 在官方的React Native仓库上贡献。

# 5.行为准则 (5. Code of Conduct) #

A code of conduct is something that most people who are part of groups or communities would be aware of. In an open-source project, it also takes the literal meaning. A code of conduct defines best practices or guidelines on how to interact and communicate in the community. It will define the project’s community standards and contain principles on being inclusive of all contributors. It can also be the go-to document to resolve conflicts between community members, sort of like an unofficial legal handbook. It may also define the rules, regulations, and legal standpoints that govern a project.

行为准则是大多数团体或社区成员都应该知道的事情。 在一个开源项目中，它也具有字面意义。 行为准则定义了有关如何在社区中进行交互和交流的最佳实践或准则。 它将定义项目的社区标准，并包含有关将所有贡献者包括在内的原则。 它也可以作为解决社区成员之间冲突的首选文件，类似于非正式的法律手册。 它还可以定义管理项目的规则，法规和法律立场。

This is an important file if you want to promote a culture of mutual respect, diversity, and inclusion within the project’s community.

如果您想在项目社区中促进相互尊重，多样性和包容性的文化，这是一个重要的文件。

You can add a code of conduct to the project by creating a file named `CODE_OF_CONDUCT.md`*.* This can also be done by using the “Add file” option in GitHub where you can also find various templates for a code of conduct.

您可以通过创建一个名为`CODE_OF_CONDUCT.md`的文件来向项目添加行为准则*。* 这也可以通过使用GitHub中的“添加文件”选项来完成，您还可以在其中找到各种行为准则模板。

![Image for post][Image for post 4]

Code of conduct on the official React Native repository. 官方React Native存储库上的行为准则。

# 奖金：作者 (Bonus: AUTHORS) #

This one is not necessary, but it’s good to have in any open-source project. This file contains a list of all the teams and people that have contributed to the project at some point. This is like a perk for any contributor to have their name (org name) listed in the repository, which gives them visibility in the tech community. To add this file, simply create an `AUTHORS` file in the project and add a format to add names using comments in the file.

这不是必需的，但是在任何开源项目中都可以使用。 该文件包含某个时刻为项目做出贡献的所有团队和人员的列表。 对于任何贡献者来说，在存储库中列出其姓名(组织名称)就像是振作，这使他们在技术社区中具有可见性。 要添加此文件，只需在项目中创建一个`AUTHORS`文件，然后添加格式以使用文件中的注释添加名称。

![Image for post][Image for post 5]

Authors on the official Flutter repository. Flutter官方存储库上的作者。

# 结论 (Conclusion) #

You may have noticed that most guidelines mentioned in the article revolve around GitHub. That is because it is the place where open-source *happens.* But having these files in the repository will help regardless of the platform where the code is stored.

您可能已经注意到，本文中提到的大多数指南都围绕GitHub展开。 那是因为它是发生开源的地方*。* 但是，无论存储代码的平台如何，将这些文件存储在存储库中都会有所帮助。

If you have any suggestions for files to be included in a repository, leave them in the comments.

如果您对将文件包含在存储库中有任何建议，请将其保留在注释中。

> 翻译自: [https://medium.com/better-programming/5-files-that-every-open-source-project-should-have-d75477796926][https_medium.com_better-programming_5-files-that-every-open-source-project-should-have-d75477796926]

开源 项目文件 管理

--------------------

开源许可对于一个开源项目而言是必需的，很多开源项目对于以上的5个文件只具备这一个。

[Choosealicense]: https://choosealicense.com/
[Image for post]: /images/20221005/601b3d49092d4837bf6dabf9c94f689f.png
[README]: https://en.wikipedia.org/wiki/README
[page]: https://github.com/matiassingers/awesome-readme
[Matias]: https://github.com/matiassingers
[Image for post 1]: /images/20221005/820a79f8b4704ac19dda17b57a7cfcd2.png
[GitHub_s docs]: https://docs.github.com/en/enterprise/2.15/user/articles/about-code-owners
[Image for post 2]: /images/20221005/bda585aa65d04820ab57559d3ece6121.png
[Image for post 3]: /images/20221005/411bcd3f908e4f80bfc3cc7e8279366b.png
[Image for post 4]: /images/20221005/c0c6b5ac78e1438e9388f6b18dc30528.png
[Image for post 5]: /images/20221005/c7f9870c28fb4914a9b05f9ffd55d407.png
[https_medium.com_better-programming_5-files-that-every-open-source-project-should-have-d75477796926]: https://medium.com/better-programming/5-files-that-every-open-source-project-should-have-d75477796926