diff --git a/.gitignore b/.gitignore index 78bea3c..42e6959 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,5 @@ _staging/ .venv/ node_modules/ *.mo +__pycache__/ +*.pyc diff --git a/_static/custom.css b/_static/custom.css index 0383ad8..d7d3687 100644 --- a/_static/custom.css +++ b/_static/custom.css @@ -31,3 +31,32 @@ .bd-article-container a.reference.internal[href^="#fn-"] { white-space: nowrap; } + +/* Task lists (MyST "tasklist" extension): render checkboxes via CSS and keep + the list compact instead of the spacious paragraph-wrapped default. + + The checkbox the extension emits lives inside the translatable + paragraph, so it disappears from translated (e.g. zh_CN) output. We hide the + real input and draw a ☐ with a pseudo-element instead, so every language + renders an identical checkbox. */ +.bd-article-container ul.contains-task-list { + list-style: none; + padding-left: 0.5rem; +} + +.bd-article-container li.task-list-item { + margin-bottom: 0.15rem; +} + +.bd-article-container li.task-list-item > p { + margin-bottom: 0; +} + +.bd-article-container li.task-list-item input.task-list-item-checkbox { + display: none; +} + +.bd-article-container li.task-list-item > p::before { + content: "\2610"; /* ☐ ballot box */ + margin-right: 0.5rem; +} diff --git a/conf.py b/conf.py index 62babd4..ee9946f 100644 --- a/conf.py +++ b/conf.py @@ -1,9 +1,12 @@ import os +import sys + +sys.path.insert(0, os.path.abspath("tools/sphinx_ext")) project = "The Open Source Way" author = "The Open Source Way contributors" -extensions = ["myst_parser"] +extensions = ["myst_parser", "cjk_emphasis"] templates_path = [os.path.abspath("_templates")] html_static_path = [os.path.abspath("_static")] html_css_files = ["custom.css"] @@ -24,6 +27,7 @@ locale_dirs = [os.path.abspath("locales")] gettext_compact = False +myst_enable_extensions = ["colon_fence", "tasklist"] myst_heading_anchors = 3 language = "en" @@ -34,13 +38,25 @@ html_theme = "sphinx_book_theme" html_title = project html_theme_options = { - "repository_url": "https://github.com/theopensourceway/production", + # The repository button and edit/issue links point at the guidebook repo, + # which holds the editorial content most readers will want to report on. + "repository_url": "https://github.com/theopensourceway/guidebook", "repository_branch": "main", - "path_to_docs": "guidebook", + "path_to_docs": "", "use_edit_page_button": True, "use_issues_button": True, "use_repository_button": True, "use_download_button": False, + # A secondary icon link points at the production repo for build toolchain, + # CI, and theme issues. + "icon_links": [ + { + "name": "Build toolchain (production)", + "url": "https://github.com/theopensourceway/production", + "icon": "fa-solid fa-screwdriver-wrench", + "type": "fontawesome", + }, + ], "home_page_in_toc": True, "show_navbar_depth": 1, "max_navbar_depth": 3, diff --git a/locales/zh_CN/LC_MESSAGES/attracting-users/communication-norms-in-open-source-software-projects.po b/locales/zh_CN/LC_MESSAGES/attracting-users/communication-norms-in-open-source-software-projects.po index c8c96ed..1c279ed 100644 --- a/locales/zh_CN/LC_MESSAGES/attracting-users/communication-norms-in-open-source-software-projects.po +++ b/locales/zh_CN/LC_MESSAGES/attracting-users/communication-norms-in-open-source-software-projects.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: The Open Source Way \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 1970-01-01 00:00+0000\n" +"POT-Creation-Date: 1970-01-01 00:00+0800\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: zh_CN\n" @@ -27,37 +27,37 @@ msgstr "开源项目中的沟通规范" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:8 msgid "" "While the tools projects use to communicate continually evolve, best " -"practices for communicating among project participants rarely change. This " -"chapter will cover the basics of project communications and offer advice on " -"serving a global audience by making the best use of particular tools and " -"platforms. We'll see how certain norms and techniques for maintaining " -"productive communication in your community will ring true everywhere, " -"regardless of the communication tools or platforms a project chooses. And we" -" will conclude with some observations on the ways ever-changing tooling and " -"communication practices in open source projects may present challenges for " -"the outside observer—particularly academic researchers—along with " -"recommendations for mitigating those challenges in a way that benefits all " -"project participants." +"practices for communicating among project participants rarely change. " +"This chapter will cover the basics of project communications and offer " +"advice on serving a global audience by making the best use of particular " +"tools and platforms. We'll see how certain norms and techniques for " +"maintaining productive communication in your community will ring true " +"everywhere, regardless of the communication tools or platforms a project " +"chooses. And we will conclude with some observations on the ways ever-" +"changing tooling and communication practices in open source projects may " +"present challenges for the outside observer—particularly academic " +"researchers—along with recommendations for mitigating those challenges in" +" a way that benefits all project participants." msgstr "尽管项目使用的沟通工具不断演进,但项目参与者之间的最佳沟通实践却鲜少改变。本章将涵盖项目沟通的基本要点,并就如何通过善用特定工具与平台服务全球受众提供建议。我们将看到,无论项目选择何种沟通工具或平台,那些维系社区高效沟通的规范与技巧在任何地方都同样适用。最后,我们将探讨开源项目中不断变化的工具与沟通实践如何给外部观察者(尤其是学术研究者)带来挑战,并提出缓解这些挑战的建议,以惠及所有项目参与者。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:10 msgid "" -"The evolution of communication platforms in free and open source software " -"projects" +"The evolution of communication platforms in free and open source software" +" projects" msgstr "自由和开源软件项目中沟通平台的演进" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:12 msgid "" -"As the number of free and open source software projects has increased over " -"time, the communication tools projects use—both to connect with their users " -"and to coordinate their developers and contributors—have evolved. Internet " -"Relay Chat (IRC) was once the default choice for real-time project chat. " -"Many large projects conducted development discussions solely via their " -"electronic mailing lists. " -"[Freshmeat](https://en.wikipedia.org/wiki/Freecode) was the place to hear " -"about new project releases or updates to existing projects. Discussions " -"about feature design and project improvements occurred via email and were " -"included in a project's mailing list archives." +"As the number of free and open source software projects has increased " +"over time, the communication tools projects use—both to connect with " +"their users and to coordinate their developers and contributors—have " +"evolved. Internet Relay Chat (IRC) was once the default choice for real-" +"time project chat. Many large projects conducted development discussions " +"solely via their electronic mailing lists. " +"[Freshmeat](https://en.wikipedia.org/wiki/Freecode) was the place to hear" +" about new project releases or updates to existing projects. Discussions " +"about feature design and project improvements occurred via email and were" +" included in a project's mailing list archives." msgstr "随着自由开源软件项目数量的增长,项目使用的沟通工具——无论是连接用户还是协调开发者与贡献者——都经历了演变。互联网中继聊天(IRC)曾是实时项目交流的首选方案,许多大型项目仅通过邮件列表进行开发讨论。[Freshmeat](https://en.wikipedia.org/wiki/Freecode)曾是了解新项目发布或现有项目更新的主要平台,而功能设计和项目改进的讨论则通过电子邮件展开,并归档在项目的邮件列表存档中。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:14 @@ -66,44 +66,45 @@ msgstr "如今,这一格局已发生多方面的转变。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:16 msgid "" -"While real-time chat is perhaps less common today, projects have not forgone" -" it entirely. Many projects have simply adopted services that are considered" -" more user-friendly or accessible, for example, Matrix, Slack, RocketChat, " -"and others. A project may even use a tool to bridge back to older chat " -"systems such as IRC in order to help a community evolve to include newer " -"services." +"While real-time chat is perhaps less common today, projects have not " +"forgone it entirely. Many projects have simply adopted services that are " +"considered more user-friendly or accessible, for example, Matrix, Slack, " +"RocketChat, and others. A project may even use a tool to bridge back to " +"older chat systems such as IRC in order to help a community evolve to " +"include newer services." msgstr "" "尽管实时聊天在当前或许不如往日普遍,但项目并未完全放弃这种形式。许多项目转而采用被认为更友好或更易接入的服务,例如 " -"Matrix、Slack、RocketChat 等。有些项目甚至会使用桥接工具兼容旧版聊天系统(如 IRC),以帮助社区逐步过渡到包含新型服务的生态中。" +"Matrix、Slack、RocketChat 等。有些项目甚至会使用桥接工具兼容旧版聊天系统(如 " +"IRC),以帮助社区逐步过渡到包含新型服务的生态中。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:18 msgid "" "Some communities still employ email for asynchronous communications, and " -"others have found they can achieve better results by offering their users " -"the opportunity to collaborate in online forums, a format more familiar to " -"many developers who began coding at the same time they were sharing news and" -" perspectives on then-new and popular forum sites like Reddit and Imgur. " -"Forum advocates find the visual layout more appealing, and forum " -"administrators often prefer the medium's fine grained access controls easier" -" to use for moderation. (For example, being able to stop all posts in a " -"particular thread during a heated discussion is relatively easy via most " -"forum software—not so with mailing lists.)" +"others have found they can achieve better results by offering their users" +" the opportunity to collaborate in online forums, a format more familiar " +"to many developers who began coding at the same time they were sharing " +"news and perspectives on then-new and popular forum sites like Reddit and" +" Imgur. Forum advocates find the visual layout more appealing, and forum " +"administrators often prefer the medium's fine grained access controls " +"easier to use for moderation. (For example, being able to stop all posts " +"in a particular thread during a heated discussion is relatively easy via " +"most forum software—not so with mailing lists.)" msgstr "" -"部分社区仍采用电子邮件进行异步沟通,而另一些社区则发现通过提供在线论坛协作机会能取得更好效果——这种形式对许多开发者而言更为熟悉,他们最初编程时恰逢 " -"Reddit 和 Imgur " +"部分社区仍采用电子邮件进行异步沟通,而另一些社区则发现通过提供在线论坛协作机会能取得更好效果——这种形式对许多开发者而言更为熟悉,他们最初编程时恰逢" +" Reddit 和 Imgur " "等新兴热门论坛兴起,习惯于在此类平台分享资讯与观点。论坛支持者认为其视觉布局更具吸引力,管理员也偏好该媒介精细的权限控制功能,这些功能使内容管理更为便捷(例如在激烈讨论中暂停特定主题下的所有发帖,通过多数论坛软件即可轻松实现——邮件列表则难以做到这点)。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:20 msgid "" -"While sites life [Freshcode](https://freshcode.club/) maintain the spirit of" -" earlier days, free and open source software projects have also made " -"extensive use of social media services like X and Facebook to interact with " -"their user and developer communities. Social media serves as an excellent " -"vehicle for project marketing and keeping audiences abreast of major project" -" developments." +"While sites life [Freshcode](https://freshcode.club/) maintain the spirit" +" of earlier days, free and open source software projects have also made " +"extensive use of social media services like X and Facebook to interact " +"with their user and developer communities. Social media serves as an " +"excellent vehicle for project marketing and keeping audiences abreast of " +"major project developments." msgstr "" -"虽然像[Freshcode](https://freshcode.club/)等网站延续了早期精神,自由开源软件项目也广泛利用 X 和 Facebook" -" 等社交媒体服务与用户及开发者群体互动。社交媒体是项目推广的绝佳渠道,能帮助受众及时了解重大项目进展。" +"虽然像[Freshcode](https://freshcode.club/)等网站延续了早期精神,自由开源软件项目也广泛利用 X 和 " +"Facebook 等社交媒体服务与用户及开发者群体互动。社交媒体是项目推广的绝佳渠道,能帮助受众及时了解重大项目进展。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:22 msgid "Social media also provides a vehicle for:" @@ -135,22 +136,22 @@ msgstr "许多用户现在期望通过这些平台获得基础技术支持" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:30 msgid "" -"While mailing list archives may no longer serve as a definitive record of " -"project discussions, GitHub's popularity as an online development and " -"collaboration platform, has meant many projects now manage their development" -" discussions via GitHub issues. GitHub's issues can have _tags_ to " -"differentiate, for instance, between discussions addressing implementation " -"of a new feature and those reporting that the software does not work as " -"intended." +"While mailing list archives may no longer serve as a definitive record of" +" project discussions, GitHub's popularity as an online development and " +"collaboration platform, has meant many projects now manage their " +"development discussions via GitHub issues. GitHub's issues can have " +"_tags_ to differentiate, for instance, between discussions addressing " +"implementation of a new feature and those reporting that the software " +"does not work as intended." msgstr "" -"虽然邮件列表存档可能不再作为项目讨论的权威记录,但 GitHub 作为在线开发和协作平台的流行,意味着许多项目现在通过 GitHub issues " -"来管理开发讨论。GitHub issues 可以使用标签进行区分,例如区分关于新功能实现的讨论和报告软件未按预期工作的讨论。" +"虽然邮件列表存档可能不再作为项目讨论的权威记录,但 GitHub 作为在线开发和协作平台的流行,意味着许多项目现在通过 GitHub issues" +" 来管理开发讨论。GitHub issues 可以使用标签进行区分,例如区分关于新功能实现的讨论和报告软件未按预期工作的讨论。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:32 msgid "" "And yet while the tools free and open source projects use to achieve " -"communication are rapidly evolving, the human needs for both information and" -" a sense of connection have not changed." +"communication are rapidly evolving, the human needs for both information " +"and a sense of connection have not changed." msgstr "然而,尽管自由开源项目用于实现沟通的工具在快速发展,人类对信息和连接感的需求却始终未变。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:34 @@ -163,33 +164,35 @@ msgstr "卓越沟通的成就" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:38 msgid "" -"People must understand the \"who,\" \"what,\" \"where,\" \"when,\" \"why,\" " -"and \"how\" of working with an open source software community. Thoughtfully " -"established and well-maintained communication channels enable open source " -"project and its participants to:" +"People must understand the \"who,\" \"what,\" \"where,\" \"when,\" " +"\"why,\" and \"how\" of working with an open source software community. " +"Thoughtfully established and well-maintained communication channels " +"enable open source project and its participants to:" msgstr "人们必须理解与开源软件社区合作的\"对象\"、\"内容\"、\"地点\"、\"时间\"、\"原因\"及\"方式\"。经过深思熟虑建立并妥善维护的沟通渠道,能使开源项目及其参与者实现以下目标:" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:40 msgid "" -"Establish shared understanding of what the software it is, why people may " -"wish to use it, and how they can get started doing so." +"Establish shared understanding of what the software it is, why people may" +" wish to use it, and how they can get started doing so." msgstr "建立对软件本身的共识理解——包括软件是什么、人们为何要使用它,以及如何上手使用。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:41 msgid "" -"Educate the community about how to use the software and how to contribute to" -" the project." +"Educate the community about how to use the software and how to contribute" +" to the project." msgstr "向社区传授如何使用该软件以及如何为项目做出贡献。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:42 msgid "" -"Keep people informed about project events (like a conference or webinar) and" -" developments (like a new software feature, the formation of a working " -"group, or the arrival of new contributors)." +"Keep people informed about project events (like a conference or webinar) " +"and developments (like a new software feature, the formation of a working" +" group, or the arrival of new contributors)." msgstr "及时向成员通报项目动态(如会议、网络研讨会等)和最新进展(如新增软件功能、工作组成立或新贡献者加入)。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:43 -msgid "Preserve knowledge about the project's decision-making norms and practices." +msgid "" +"Preserve knowledge about the project's decision-making norms and " +"practices." msgstr "记录并传承项目决策规范与实践经验。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:44 @@ -207,9 +210,9 @@ msgstr "在参与者中培养共同的兴趣和目标意识,并为项目成员 #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:46 msgid "" -"Provide a location for contributors to the project to collaborate, be it on " -"documentation for the project or to discuss how a particular part of the " -"code base should be refactored." +"Provide a location for contributors to the project to collaborate, be it " +"on documentation for the project or to discuss how a particular part of " +"the code base should be refactored." msgstr "为项目贡献者提供一个协作空间,无论是编写项目文档还是讨论代码库特定部分的重构方案。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:48 @@ -228,33 +231,32 @@ msgstr "在编写项目文档和其他信息资源时,需认识到这些内容 msgid "" "For example, consider the basic distinction between project _users_ and " "project _developers_. Someone interested in _using_ the software will be " -"interested in things like how to install it, how to configure it, and what " -"they need to know to accomplish the task at hand (e.g., build a website). " -"Developers will also be interested in such details, but will need additional" -" detail if they are going to contribute effectively to the project." +"interested in things like how to install it, how to configure it, and " +"what they need to know to accomplish the task at hand (e.g., build a " +"website). Developers will also be interested in such details, but will " +"need additional detail if they are going to contribute effectively to the" +" project." msgstr "例如,考虑项目_用户_和项目_开发者_之间的基本区别。想_使用_软件感兴趣的人会关心如何安装、如何配置以及完成手头任务(如搭建网站)所需了解的内容。开发者同样会关注这些细节,但如果要有效参与项目贡献,他们还需要更多详细信息。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:54 msgid "" "If your project observes certain coding conventions, be sure to include " -"those conventions in the developer documentation. Having a patch rejected by" -" a maintainer because you haven't indented code a certain way can be rather " -"demotivating. Users, however, likely won't need these details." +"those conventions in the developer documentation. Having a patch rejected" +" by a maintainer because you haven't indented code a certain way can be " +"rather demotivating. Users, however, likely won't need these details." msgstr "如果项目遵循特定的编码规范,请务必在开发者文档中明确说明这些规范。因为代码缩进方式不合要求而被维护者拒绝补丁,可能会大大打击贡献者的积极性。但对于用户来说,这些技术细节通常并不必要。" -#: ../../attracting-users/communication-norms-in-open-source-software-projects.md:56 +#: ../../attracting-users/communication-norms-in-open-source-software-projects.md:57 #, python-brace-format, python-format msgid "" -"{% hint style=\"success\" %} Develop a style guide for your project and make" -" sure it is easy to find in your developer-oriented documentation. Not every" -" project will create its own style guide, but it is best practice to note " -"what coding conventions the project will observe. If the project uses a " -"previously published style guide, make sure to link to it in the developer " -"documentation[^guides]. {% endhint %}" +"Develop a style guide for your project and make sure it is easy to find " +"in your developer-oriented documentation. Not every project will create " +"its own style guide, but it is best practice to note what coding " +"conventions the project will observe. If the project uses a previously " +"published style guide, make sure to link to it in the developer " +"documentation[^guides]." msgstr "" -"{% hint style=\"success\" %} " "为项目制定风格指南,并确保在面向开发者的文档中易于查找。并非所有项目都需要创建自己的风格指南,但注明项目将遵循的代码规范是最佳实践。如果项目采用已发布的风格指南,务必在开发者文档[^guides]中提供其链接。" -" {% endhint %}" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:60 msgid "The virtual showcase: Crafting your project's website" @@ -262,18 +264,18 @@ msgstr "虚拟展示:精心打造项目网站" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:62 msgid "" -"When people are looking for information about software that may help them " -"solve a problem, their first stop will likely be the project website." +"When people are looking for information about software that may help them" +" solve a problem, their first stop will likely be the project website." msgstr "当人们寻找可能帮助他们解决问题的软件信息时,他们的第一站很可能是项目网站。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:64 msgid "" -"A project website needn't be intricately designed to be effective (though a " -"more attractive site aids with project marketing). A thorough `README.md` " -"file on GitHub can work well as a project website, provided the information " -"it offers gives users and potential contributors a sufficient overview of " -"the project. A basic project website should feature at least the following " -"sections." +"A project website needn't be intricately designed to be effective (though" +" a more attractive site aids with project marketing). A thorough " +"`README.md` file on GitHub can work well as a project website, provided " +"the information it offers gives users and potential contributors a " +"sufficient overview of the project. A basic project website should " +"feature at least the following sections." msgstr "" "项目网站无需复杂设计也能发挥作用(尽管更美观的站点有助于项目推广)。GitHub " "上详尽的`README.md`文件完全可以充当项目网站,只要其提供的信息能让用户和潜在贡献者对项目有充分了解。基础项目网站至少应包含以下部分。" @@ -284,20 +286,21 @@ msgstr "项目概述" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:68 msgid "" -"Include a simple overview of the project in an easy-to-spot location on the " -"project website. This project description should include what the code base " -"is designed to do and what problems someone might solve by using it. Making " -"this information succinct and easy to find is critical. Post a quick " -"description on the project's home page so that interested parties " -"immediately discover if the project is designed to meet their needs." +"Include a simple overview of the project in an easy-to-spot location on " +"the project website. This project description should include what the " +"code base is designed to do and what problems someone might solve by " +"using it. Making this information succinct and easy to find is critical. " +"Post a quick description on the project's home page so that interested " +"parties immediately discover if the project is designed to meet their " +"needs." msgstr "在项目网站的显眼位置简要概述项目内容。项目描述应包含代码库的设计用途以及使用者可能解决的问题。确保这些信息简洁明了且易于查找至关重要。在项目主页发布简短说明,让感兴趣的人能立即判断该项目是否符合其需求。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:70 msgid "" -"Think of this information as the opportunity to explain to someone who has " -"never heard of your project why it could matter to them—in 30 seconds or " -"less. For example, Drupal's [about page](https://www.drupal.org/about) " -"describes the project this way:" +"Think of this information as the opportunity to explain to someone who " +"has never heard of your project why it could matter to them—in 30 seconds" +" or less. For example, Drupal's [about " +"page](https://www.drupal.org/about) describes the project this way:" msgstr "" "请将这段信息视为向从未听说过你项目的人解释它为何重要的机会——用 30 秒或更短时间。例如,Drupal " "的[简介页面](https://www.drupal.org/about)是这样描述该项目的:" @@ -306,10 +309,10 @@ msgstr "" msgid "" "Drupal is content management software. It's used to make many of the " "websites and applications you use every day. Drupal has great standard " -"features, like easy content authoring, reliable performance, and excellent " -"security. But what sets it apart is its flexibility; modularity is one of " -"its core principles. Its tools help you build the versatile, structured " -"content that dynamic web." +"features, like easy content authoring, reliable performance, and " +"excellent security. But what sets it apart is its flexibility; modularity" +" is one of its core principles. Its tools help you build the versatile, " +"structured content that dynamic web." msgstr "" "Drupal 是内容管理软件。你日常使用的许多网站和应用程序都由它构建而成。Drupal " "具备出色的标准功能,例如便捷的内容创作、可靠的性能以及卓越的安全性。但使其与众不同的是其灵活性——模块化设计正是其核心理念之一。其工具能帮助你构建动态网络体验所需的多样化、结构化内容。" @@ -338,18 +341,19 @@ msgstr "让我们再看一个流行项目的例子:Kubernetes。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:82 msgid "" -"When visiting the project home page, [kubernetes.io](http://kubernetes.io/)," -" a visitor immediately sees the following explanation:" +"When visiting the project home page, " +"[kubernetes.io](http://kubernetes.io/), a visitor immediately sees the " +"following explanation:" msgstr "当访问项目主页[kubernetes.io](http://kubernetes.io/)时,访客立即看到以下说明:" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:84 msgid "" "Kubernetes (K8s) is an open-source system for automating deployment, " -"scaling, and management of containerized applications. It groups containers " -"that make up an application into logical units for easy management and " -"discovery. Kubernetes builds upon 15 years of experience of running " -"production workloads at Google, combined with best-of-breed ideas and " -"[practices from the community](https://kubernetes.io/)." +"scaling, and management of containerized applications. It groups " +"containers that make up an application into logical units for easy " +"management and discovery. Kubernetes builds upon 15 years of experience " +"of running production workloads at Google, combined with best-of-breed " +"ideas and [practices from the community](https://kubernetes.io/)." msgstr "" "Kubernetes(K8s)是一个用于自动化部署、扩展和管理容器化应用程序的开源系统。它将构成应用程序的容器分组为逻辑单元,便于管理和发现。Kubernetes" " 基于 Google 15 年生产环境工作负载的运行经验,并结合了来自[社区的](https://kubernetes.io/)最佳创意和实践。" @@ -367,28 +371,29 @@ msgstr "Kubernetes 是什么。(它是一个用于管理容器化应用程序 #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:89 msgid "" "How Kubernetes is abbreviated. (Little details like this one immediately " -"deepen the comfort level of new arrivals; no one is expected to already know" -" an arcane acronym upon arrival.)" +"deepen the comfort level of new arrivals; no one is expected to already " +"know an arcane acronym upon arrival.)" msgstr "Kubernetes 的缩写规则。(这类细节能迅速提升新成员的熟悉度——没有人会被要求事先掌握晦涩的缩写。)" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:90 msgid "" -"Where Kubernetes was developed. (Google is noted as the originator of this " -"code base, establishing the project as focused on enterprise applications " -"and providing confidence that the software is well designed and maintained.)" +"Where Kubernetes was developed. (Google is noted as the originator of " +"this code base, establishing the project as focused on enterprise " +"applications and providing confidence that the software is well designed " +"and maintained.)" msgstr "Kubernetes 的诞生地。(谷歌被标注为该代码库的创始者,表明该项目专注于企业级应用,并确保软件设计精良且维护良好。)" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:91 msgid "" -"Kubernetes is open source. (A user can expect to use, run, modify, and share" -" changes to the code base; any questions about barriers to entry due to " -"licensing fees, procurement processes, etc., are dismissed.)" +"Kubernetes is open source. (A user can expect to use, run, modify, and " +"share changes to the code base; any questions about barriers to entry due" +" to licensing fees, procurement processes, etc., are dismissed.)" msgstr "Kubernetes 是开源的。(用户可以自由使用、运行、修改及共享代码变更;任何关于许可费用、采购流程等准入门槛的疑虑都不复存在。)" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:92 msgid "" -"The project values community engagement. (One can expect that contributions " -"of code, documentation, etc., are welcome and encouraged.)" +"The project values community engagement. (One can expect that " +"contributions of code, documentation, etc., are welcome and encouraged.)" msgstr "本项目重视社区参与。(可以预期,代码、文档等贡献是受欢迎且受鼓励的。)" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:94 @@ -398,33 +403,32 @@ msgstr "快速入门" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:96 msgid "" "The processes for creating good \"getting started\" " -"documentation—occasionally called \"onboarding documentation\"—are outside " -"the scope of this chapter. (Refer to the dedicated onboarding chapter in " -"this guidebook for more detail.) Here, suffice it to say that open source " -"project websites should feature a section aimed at helping new users and " -"potential contributors get started using the software. Clearly labeling that" -" section \"getting started\" or \"new users\" makes finding that section " -"easy when people need it. Further differentiating between \"new users\" and " -"\"new contributors\" in your onboarding documentation is even better, as " -"these two audiences have very different needs. Clearly pointing to these " -"resources for newcomers on the project website helps to keep the project's " -"other communication channels—like the forums and real-time chat rooms—free " -"from frequently repeated inquiries about how to get started." +"documentation—occasionally called \"onboarding documentation\"—are " +"outside the scope of this chapter. (Refer to the dedicated onboarding " +"chapter in this guidebook for more detail.) Here, suffice it to say that " +"open source project websites should feature a section aimed at helping " +"new users and potential contributors get started using the software. " +"Clearly labeling that section \"getting started\" or \"new users\" makes " +"finding that section easy when people need it. Further differentiating " +"between \"new users\" and \"new contributors\" in your onboarding " +"documentation is even better, as these two audiences have very different " +"needs. Clearly pointing to these resources for newcomers on the project " +"website helps to keep the project's other communication channels—like the" +" forums and real-time chat rooms—free from frequently repeated inquiries " +"about how to get started." msgstr "编写优秀\"入门\"文档(有时称为\"上手文档\")的流程不在本章讨论范围内。(详见本指南专设的\"新手指引\"章节。)此处只需明确:开源项目网站应设立专门板块,帮助新用户和潜在贡献者开始使用软件。将该板块清晰标注为\"入门指南\"或\"新用户\"能让人在需要时轻松找到。若能在新手指引文档中进一步区分\"新用户\"与\"新贡献者\"则更为理想,因为这两个群体的需求差异显著。在项目网站上为新人明确指引这些资源,有助于避免论坛和实时聊天室等沟通渠道反复出现\"如何上手\"的重复提问。" -#: ../../attracting-users/communication-norms-in-open-source-software-projects.md:98 +#: ../../attracting-users/communication-norms-in-open-source-software-projects.md:99 #, python-brace-format, python-format msgid "" -"{% hint style=\"success\" %} In your project's \"getting started\" guide for" -" new users and participants, include any information you can about other " -"places those unfamiliar with the project can get help. For example, you may " -"have a Slack channel called \"newbies\" staffed by folks who enjoy mentoring" -" and helping people get started, whereas ongoing development discussions may" -" take place in the \"developer\" channel. {% endhint %}" +"In your project's \"getting started\" guide for new users and " +"participants, include any information you can about other places those " +"unfamiliar with the project can get help. For example, you may have a " +"Slack channel called \"newbies\" staffed by folks who enjoy mentoring and" +" helping people get started, whereas ongoing development discussions may " +"take place in the \"developer\" channel." msgstr "" -"{% hint style=\"success\" %} " "在项目的新手入门指南中,为初次接触项目的用户和参与者提供所有能获取帮助的渠道信息。例如:可以设置名为\"新手区\"的 Slack " -"频道,由乐于指导新人上手的成员提供支持;而持续性的开发讨论则可在\"开发者\"频道进行。 {% endhint %}" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:102 msgid "Frequently asked questions" @@ -432,16 +436,16 @@ msgstr "常见问题" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:104 msgid "" -"Another excellent location to feature basic information about your project " -"is a frequently asked questions (FAQ) page. If project development is just " -"beginning, a basic FAQ detailing what the project is, what the code base is " -"used for, and how someone can get access to the code is sufficient. However," -" as more people join the project—new users, developers, documentarians, " -"etc.—you will likely find yourself answering the same basic questions " -"repeatedly. (And in the process you'll discover that many aspects of the " -"projects are not as obvious to newcomers as they are to you.) These repeat " -"questions represent opportunities to improve your documentation and to seek " -"help from your community." +"Another excellent location to feature basic information about your " +"project is a frequently asked questions (FAQ) page. If project " +"development is just beginning, a basic FAQ detailing what the project is," +" what the code base is used for, and how someone can get access to the " +"code is sufficient. However, as more people join the project—new users, " +"developers, documentarians, etc.—you will likely find yourself answering " +"the same basic questions repeatedly. (And in the process you'll discover " +"that many aspects of the projects are not as obvious to newcomers as they" +" are to you.) These repeat questions represent opportunities to improve " +"your documentation and to seek help from your community." msgstr "" "展示项目基本信息的另一绝佳位置是常见问题解答(FAQ)页面。若项目开发尚处初期阶段,只需准备基础 " "FAQ,说明项目内容、代码库用途以及如何获取代码即可。但随着更多参与者加入——包括新用户、开发人员、文档编写者等——你可能会发现自己反复回答相同的基础问题。(在这个过程中,你还会发现项目的许多方面对新人而言并不像你认为的那样显而易见。)这些重复性问题正是完善文档和向社区寻求帮助的良机。" @@ -450,9 +454,10 @@ msgstr "" msgid "" "Keep your FAQ updated and easy to locate. But even better: ask community " "participants to help you improve it. When answering a question for a " -"newcomer, be it via email on the project mailing list or in real-time chat, " -"ask the newcomer to write up the question and answer for inclusion in the " -"project FAQ. By asking for help from your community, you do several things:" +"newcomer, be it via email on the project mailing list or in real-time " +"chat, ask the newcomer to write up the question and answer for inclusion " +"in the project FAQ. By asking for help from your community, you do " +"several things:" msgstr "" "保持 FAQ " "内容更新且易于查找。但更好的做法是:邀请社区成员协助完善它。无论是通过项目邮件列表回复邮件,还是在实时聊天中解答新人的疑问时,都可以请提问者将问题与答案整理成文,纳入项目" @@ -470,8 +475,8 @@ msgstr "展现对社区贡献的欢迎与鼓励。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:110 msgid "" -"Invite further contribution from someone who has already shown interest in " -"the project by asking for their help." +"Invite further contribution from someone who has already shown interest " +"in the project by asking for their help." msgstr "主动邀请已表现出项目兴趣的人进一步参与,寻求他们的帮助。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:112 @@ -480,12 +485,12 @@ msgid "" "Sending instructions for how to edit the FAQ along with your request to " "contribute to it—thus lowering the barrier to entry—makes receiving a " "contribution more likely. If your project maintains a contributors list, " -"make sure to include the people contributing to your FAQ in it. People love " -"seeing their work and contributions (however small) acknowledged. Doing so " -"gives contributors a sense of belonging and commitment to the project. " -"People who feel their work is appreciated and respected are more likely to " -"stick around and contribute to the project, whether by filing issues or " -"adding new features." +"make sure to include the people contributing to your FAQ in it. People " +"love seeing their work and contributions (however small) acknowledged. " +"Doing so gives contributors a sense of belonging and commitment to the " +"project. People who feel their work is appreciated and respected are more" +" likely to stick around and contribute to the project, whether by filing " +"issues or adding new features." msgstr "" "理想情况下,新手应能自行编辑 FAQ 文档。在请求对方贡献 FAQ " "内容时,附上编辑指南可显著降低参与门槛,从而提高贡献接收率。若项目设有贡献者名单,务必将 FAQ " @@ -497,69 +502,72 @@ msgstr "记录项目目标和非目标" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:116 msgid "" -"Your project's website should also make clear the _purpose_ of the project " -"and the _activities_ the project has as its focus. People have difficulty " -"understanding how they can best fit into a community and how they can " -"contribute if they do not understand what activities are currently in " -"progress and what is planned for the future." +"Your project's website should also make clear the _purpose_ of the " +"project and the _activities_ the project has as its focus. People have " +"difficulty understanding how they can best fit into a community and how " +"they can contribute if they do not understand what activities are " +"currently in progress and what is planned for the future." msgstr "项目网站应当清晰阐明该项目的宗旨及核心活动内容。若访客不了解当前进行中的工作与未来规划,将难以找准自身在社区中的定位,也无法明确可以贡献哪些力量。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:118 msgid "" "One common tool to communicate these goals is a project roadmap. Even if " -"your project does not yet have sufficient resources to develop this kind of " -"roadmap, you should still find some way to ensure users and would-be " -"contributors understand the project landscape. For instance, a weekly recap " -"of project activities and planned activities for the coming week or month is" -" an excellent start, and it's something you can offer through a quick blog " -"or forum post. Such works are an excellent resource for newcomers orienting " -"themselves to the project and are a wonderful place to point interested " -"parties to learn more as part of their onboarding process." +"your project does not yet have sufficient resources to develop this kind " +"of roadmap, you should still find some way to ensure users and would-be " +"contributors understand the project landscape. For instance, a weekly " +"recap of project activities and planned activities for the coming week or" +" month is an excellent start, and it's something you can offer through a " +"quick blog or forum post. Such works are an excellent resource for " +"newcomers orienting themselves to the project and are a wonderful place " +"to point interested parties to learn more as part of their onboarding " +"process." msgstr "项目路线图是传达这些目标的常用工具。即便当前资源不足以制定完整路线图,仍需设法让用户和潜在贡献者了解项目全貌。例如,通过简短的博客或论坛帖子发布每周项目进展回顾及未来周/月计划就是个良好开端。这类内容既能帮助新人快速熟悉项目,也可作为意向参与者入门引导的优质参考资料。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:120 msgid "" -"Communicating your project's _non-goals_ is equally important. Due to the " -"vibrant nature of open source projects, it is only natural that someone will" -" find a use for a project that the project's creators never intended and " -"will wish to extend the project's capabilities to target that specific use " -"case. If the project maintainers do not intend for the project to have a " -"wider focus than what is already offered, letting these would-be " -"contributors know this in advance will save everyone time and " +"Communicating your project's _non-goals_ is equally important. Due to the" +" vibrant nature of open source projects, it is only natural that someone " +"will find a use for a project that the project's creators never intended " +"and will wish to extend the project's capabilities to target that " +"specific use case. If the project maintainers do not intend for the " +"project to have a wider focus than what is already offered, letting these" +" would-be contributors know this in advance will save everyone time and " "disappointment. In this era of [easy " -"forking](https://en.wikipedia.org/wiki/Fork_\\(software_development\\)), it " -"is relatively easy for those who would use some parts of the project but not" -" others to develop and maintain a code base that better matches their own " -"needs—all without asking the maintainers of the original project to deviate " -"from their intended vision and the project scope they've set." +"forking](https://en.wikipedia.org/wiki/Fork_\\(software_development\\)), " +"it is relatively easy for those who would use some parts of the project " +"but not others to develop and maintain a code base that better matches " +"their own needs—all without asking the maintainers of the original " +"project to deviate from their intended vision and the project scope " +"they've set." msgstr "阐明项目的非目标同样重要。由于开源项目充满活力的特性,自然会有人发现项目创建者未曾设想的用途,并希望扩展项目功能以满足特定用例。如果项目维护者无意扩大项目现有范围,提前告知潜在贡献者这一立场,将为所有人节省时间和避免失望。在这个[轻松分叉](https://en.wikipedia.org/wiki/Fork_\\(software_development\\))的时代,那些只想使用项目部分功能的人可以相对容易地开发和维护更符合自身需求的代码库——完全无需要求原项目维护者偏离既定愿景和已规划的项目范畴。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:122 msgid "" "Documenting non-goals is also particularly important for commercially " -"focused projects, where a contributor's desire to create a feature as open " -"source may be in conflict with vendor goals for creating proprietary " -"features. Contributors may still choose to create that feature as open " -"source, but they should know from the start that upstream maintainers do not" -" intend to include their work as part of the project's code base. Some may " -"choose to not implement the feature, knowing that a vendor is creating it " -"for them; still others may choose not to implement the feature if they know " -"it will not be included in the project's mainline source tree, as they do " -"not wish to incur the burden of ongoing maintenance themselves. And others " -"may choose to go ahead and create something that works well for them and " -"release it as open source, regardless of whether the feature is incorporated" -" into the project's main source repositories." +"focused projects, where a contributor's desire to create a feature as " +"open source may be in conflict with vendor goals for creating proprietary" +" features. Contributors may still choose to create that feature as open " +"source, but they should know from the start that upstream maintainers do " +"not intend to include their work as part of the project's code base. Some" +" may choose to not implement the feature, knowing that a vendor is " +"creating it for them; still others may choose not to implement the " +"feature if they know it will not be included in the project's mainline " +"source tree, as they do not wish to incur the burden of ongoing " +"maintenance themselves. And others may choose to go ahead and create " +"something that works well for them and release it as open source, " +"regardless of whether the feature is incorporated into the project's main" +" source repositories." msgstr "对于商业导向的项目而言,记录非目标同样至关重要。当贡献者希望以开源方式开发某项功能时,这可能与厂商开发专有特性的目标产生冲突。贡献者仍可选择以开源形式实现该功能,但他们应当从一开始就知晓上游维护者无意将其成果纳入项目代码库。有些人得知厂商正在开发该功能后,可能选择放弃实现;另一些人若知晓该功能不会被纳入项目主干源代码树,也可能选择放弃——因为他们不愿独自承担持续的维护负担。当然,也有人会继续开发符合自身需求的解决方案,并以开源形式发布,无论该功能最终是否被纳入项目的主源码库。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:124 msgid "" "Most important here is that no one feels _surprised_ by the direction a " -"project will take. No project needs to accept every contribution, but having" -" contributors invest time and energy into developing something only to " -"discover it will not be accepted due to a conflict with an unknown roadmap " -"(commercial or otherwise) creates tension in the community and a lack of " -"trust in the project maintainers. It can even encourage adoption of open " -"source alternatives to the vendor's product." +"project will take. No project needs to accept every contribution, but " +"having contributors invest time and energy into developing something only" +" to discover it will not be accepted due to a conflict with an unknown " +"roadmap (commercial or otherwise) creates tension in the community and a " +"lack of trust in the project maintainers. It can even encourage adoption " +"of open source alternatives to the vendor's product." msgstr "最重要的是,不要让任何人对项目的发展方向感到_意外_。虽然项目不必接受所有贡献,但如果贡献者投入时间和精力开发的内容因与未知路线图(商业或其他方面)冲突而被拒绝,这会在社区中制造紧张气氛,并导致项目维护者失去信任。甚至可能促使人们转而采用该供应商产品的开源替代方案。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:126 @@ -578,14 +586,16 @@ msgstr "什么是问题跟踪器?" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:132 msgid "" -"An _issue tracker_ (sometimes also known as a _bug tracker_, _issues list_, " -"or _issue queue_) is a tool that allows people to submit reports when they " -"encounter instances where they believe the software is not working as " -"intended[^not-working]. As a way to monitor pending tasks and allow for " -"collaborative commenting and review of work in progress, some projects " -"manage their entire development workflow via their issue trackers." +"An _issue tracker_ (sometimes also known as a _bug tracker_, _issues " +"list_, or _issue queue_) is a tool that allows people to submit reports " +"when they encounter instances where they believe the software is not " +"working as intended[^not-working]. As a way to monitor pending tasks and " +"allow for collaborative commenting and review of work in progress, some " +"projects manage their entire development workflow via their issue " +"trackers." msgstr "" -"_问题跟踪器_(issue tracker)(有时也称为_错误跟踪器_、_问题列表_或_问题队列_)是一种工具,当用户认为软件运行不符合预期[^not-" +"_问题跟踪器_(issue tracker)(有时也称为_错误跟踪器_、_问题列表_或_问题队列_)是一种工具,当用户认为软件运行不符合预期" +"[^not-" "working]时,可通过该工具提交问题报告。作为一种监控待办事项并支持对进行中的工作展开协作评论与审查的方式,部分项目会通过问题追踪器来管理整个开发流程。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:134 @@ -602,30 +612,31 @@ msgstr "为什么要提交问题?" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:138 msgid "" -"While filing an issue may seem more cumbersome than simply asking for help " -"in real-time chat, it is important to do for several reasons:" +"While filing an issue may seem more cumbersome than simply asking for " +"help in real-time chat, it is important to do for several reasons:" msgstr "虽然提交问题可能比在实时聊天中直接求助更繁琐,但这样做有几点重要原因:" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:140 msgid "" -"Project contributors cannot keep track of all conversations occurring across" -" various platforms, but they can always refer to the issue tracker to " -"improve the project." +"Project contributors cannot keep track of all conversations occurring " +"across various platforms, but they can always refer to the issue tracker " +"to improve the project." msgstr "项目贡献者无法追踪所有跨平台对话,但他们始终可以参考问题跟踪器来改进项目。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:142 msgid "" -"Real-time chat and social media are ephemeral communication channels. The " -"issue tracker is a purpose built tool for recording and reviewing problems " -"with the software. Software projects often define their upcoming work plans " -"by using their issue tracker as a key component—and perhaps their sole " -"tool—to prioritize all possible areas to work on. (Simply put, the project's" -" issue tracker is very often synonymous with the project's to-do list.) If " -"your problem does not make its way into the issue tracker, it will likely " -"not be addressed simply because a very busy person has forgotten the details" -" of the problem. For this reason, you will often find that one of the first " -"requests you receive when asking for help is to file an issue so the project" -" maintainers can keep track of the problem." +"Real-time chat and social media are ephemeral communication channels. The" +" issue tracker is a purpose built tool for recording and reviewing " +"problems with the software. Software projects often define their upcoming" +" work plans by using their issue tracker as a key component—and perhaps " +"their sole tool—to prioritize all possible areas to work on. (Simply put," +" the project's issue tracker is very often synonymous with the project's " +"to-do list.) If your problem does not make its way into the issue " +"tracker, it will likely not be addressed simply because a very busy " +"person has forgotten the details of the problem. For this reason, you " +"will often find that one of the first requests you receive when asking " +"for help is to file an issue so the project maintainers can keep track of" +" the problem." msgstr "实时聊天和社交媒体是即时性沟通渠道。问题追踪器则是专为记录和审查软件问题而构建的工具。软件项目通常通过将问题追踪器作为核心组件(甚至可能是唯一工具)来定义其近期工作计划,从而对所有待处理事项进行优先级排序。(简而言之,项目的问题追踪器往往等同于项目的待办事项清单。)如果你的问题未被录入问题追踪器,它很可能因忙碌者遗忘细节而无法得到解决。正因如此,当你寻求帮助时,往往会首先被要求提交问题报告,以便项目维护者能够持续跟踪该问题。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:144 @@ -637,30 +648,30 @@ msgstr "提交问题能让你与项目贡献者就问题进行异步沟通,因 #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:146 msgid "" -"When you've uncovered a problem with the software, you might discover that " -"the problem is actually the root cause of _another_ problem, or there may be" -" a way in which _several_ problems are related. Issue tracking software " -"allows project developers to group related issues together, which may aid in" -" diagnosing a problem's root cause." +"When you've uncovered a problem with the software, you might discover " +"that the problem is actually the root cause of _another_ problem, or " +"there may be a way in which _several_ problems are related. Issue " +"tracking software allows project developers to group related issues " +"together, which may aid in diagnosing a problem's root cause." msgstr "当你发现软件存在问题时,可能会意识到该问题实际上是_另一个_问题的根本原因,或者存在_多个_问题相互关联的情况。问题追踪软件允许项目开发者将相关问题归类,这有助于诊断问题的根源。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:148 msgid "" -"People often encounter the same issues with software, and many of them are " -"filing issues with the project. Having multiple reports of the same problem " -"can be very time consuming for the project maintainers, as they then need to" -" respond to each individual reporter about work in progress. Fortunately, " -"issue trackers make this process easier for maintainers by allowing them to " -"quickly close issues by stating they are duplicates of an existing one (and " -"then asking the bug reporter to track work-in-progress in the \"original\" " -"report)." +"People often encounter the same issues with software, and many of them " +"are filing issues with the project. Having multiple reports of the same " +"problem can be very time consuming for the project maintainers, as they " +"then need to respond to each individual reporter about work in progress. " +"Fortunately, issue trackers make this process easier for maintainers by " +"allowing them to quickly close issues by stating they are duplicates of " +"an existing one (and then asking the bug reporter to track work-in-" +"progress in the \"original\" report)." msgstr "用户在使用软件时常常会遇到相同的问题,其中许多人会向项目提交问题报告。对于项目维护者来说,处理大量重复问题的报告会耗费大量时间,因为他们需要对每位报告者分别反馈处理进展。幸运的是,问题追踪系统能有效简化这一流程——维护者可以快速关闭重复问题(注明该问题与现有问题重复),并指引问题报告者前往\"原始\"报告跟进处理进度。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:150 msgid "" "Project maintainers can then engage in broadcast-style communication to " -"everyone experiencing the problem in one place, streamling their workflow " -"while still helping everyone who needs assistance." +"everyone experiencing the problem in one place, streamling their workflow" +" while still helping everyone who needs assistance." msgstr "项目维护者随后可在一处向所有遇到该问题的人员进行广播式沟通,既简化了工作流程,又能为所有需要帮助的人提供支持。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:152 @@ -671,16 +682,16 @@ msgstr "确保问题追踪器易于查找" msgid "" "Make sure the location of your project's issue tracker is prominently " "displayed in your FAQ, as well as in your usage and development " -"documentation. If people cannot figure out where to submit an issue, they " -"will ask someone in the project where to do so. Supporting well-meaning " -"users by offering repeated answers to basic questions like this one can be " -"quite time consuming." +"documentation. If people cannot figure out where to submit an issue, they" +" will ask someone in the project where to do so. Supporting well-meaning " +"users by offering repeated answers to basic questions like this one can " +"be quite time consuming." msgstr "确保在项目的常见问题解答(FAQ)、使用文档和开发文档中显著显示问题追踪器的位置。如果用户无法确定在哪里提交问题,他们会向项目人员询问。对于这类基础问题反复提供答案来支持热心用户可能会相当耗时。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:156 msgid "" -"Do yourself and your community a favor and make your issue tracker very easy" -" to find." +"Do yourself and your community a favor and make your issue tracker very " +"easy to find." msgstr "为你的社区和自己行个方便,让问题追踪系统一目了然。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:158 @@ -689,22 +700,23 @@ msgstr "使用问题模板" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:160 msgid "" -"Not everyone who uses your software will be familiar with your community's " -"conventions for filing a useful bug report. To save you and the bug reporter" -" time, offer an issue template to ensure you receive the information you " -"need to reproduce the reported error and effectively triage it. For example," -" you may need to know what version of the software or what operating system " -"was in use when an error occurred. If common information is required for " -"reproducing errors, ask for it in an issue template." +"Not everyone who uses your software will be familiar with your " +"community's conventions for filing a useful bug report. To save you and " +"the bug reporter time, offer an issue template to ensure you receive the " +"information you need to reproduce the reported error and effectively " +"triage it. For example, you may need to know what version of the software" +" or what operating system was in use when an error occurred. If common " +"information is required for reproducing errors, ask for it in an issue " +"template." msgstr "并非所有使用你软件的人都熟悉你社区提交有效错误报告的惯例。为了节省你和错误报告者的时间,提供一个问题模板以确保你获得重现所报告错误及有效分类所需的信息。例如,你可能需要了解错误发生时使用的软件版本或操作系统。如果需要重现错误的常见信息,请在问题模板中要求提供这些内容。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:162 msgid "" -"Common fields in issue templates include a summary of the issue, steps to " -"reproduce it, the actual behavior the user observes, the intended behavior " -"for the software, and a request for log files or screenshots to help guide " -"the issue reviewer in better understanding the bug report. Several issue " -"trackers support templates for bug reports, including " +"Common fields in issue templates include a summary of the issue, steps to" +" reproduce it, the actual behavior the user observes, the intended " +"behavior for the software, and a request for log files or screenshots to " +"help guide the issue reviewer in better understanding the bug report. " +"Several issue trackers support templates for bug reports, including " "[GitHub](https://docs.github.com/en/github/building-a-strong-community" "/configuring-issue-templates-for-your-repository), " "[GitLab](https://docs.gitlab.com/ee/user/project/description_templates.html)," @@ -719,9 +731,9 @@ msgstr "" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:164 msgid "" -"If you find yourself asking for the same information over and over again in " -"response to different bug reports, then congratulations. You have uncovered " -"an area of your template in need of improvement." +"If you find yourself asking for the same information over and over again " +"in response to different bug reports, then congratulations. You have " +"uncovered an area of your template in need of improvement." msgstr "如果你发现自己针对不同的错误报告反复询问相同的信息,那么恭喜你。你已经发现了模板中需要改进的部分。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:166 @@ -730,46 +742,47 @@ msgstr "寻求帮助:标记问题以提高清晰度并鼓励贡献" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:168 msgid "" -"Most modern issue trackers allow users to label issues they file, which can " -"be useful for organizing project work. By differentiating between different " -"types of requests—features for development, software errors, etc.—a " -"project's maintainers can be more organized and triage issues more " -"efficiently. Further, many people interested in contributing to open source " -"software projects are looking for issues on which they can work to better " -"understand the project's development mechanics. If you will actively use " -"labels in your issue tracker, make sure to document the label definitions in" -" your development documentation so those labels are used consistently (or " -"restrict the addition of issue labels to project maintainers only). A list " -"of labels used inconsistently is no more helpful than a list of " -"undifferentiated issues." +"Most modern issue trackers allow users to label issues they file, which " +"can be useful for organizing project work. By differentiating between " +"different types of requests—features for development, software errors, " +"etc.—a project's maintainers can be more organized and triage issues more" +" efficiently. Further, many people interested in contributing to open " +"source software projects are looking for issues on which they can work to" +" better understand the project's development mechanics. If you will " +"actively use labels in your issue tracker, make sure to document the " +"label definitions in your development documentation so those labels are " +"used consistently (or restrict the addition of issue labels to project " +"maintainers only). A list of labels used inconsistently is no more " +"helpful than a list of undifferentiated issues." msgstr "现代大多数问题跟踪系统都允许用户为提交的问题添加标签,这有助于项目工作的组织管理。通过区分不同类型的请求——如开发新功能、软件缺陷等——项目维护者能够更有条理地处理问题,提高分类效率。此外,许多有意参与开源软件项目的贡献者会通过查看问题列表来寻找适合自己参与的任务,从而更好地理解项目的开发机制。若计划在问题跟踪系统中积极使用标签,请务必在开发文档中明确标注各标签的定义,以确保标签使用的一致性(或仅限项目维护者添加问题标签)。一套使用混乱的标签体系,其作用与未分类的问题列表并无二致。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:170 msgid "" "Labeling issues as \"for newcomers\" or \"help wanted\" allows project " -"maintainers to flag issues particularly suited to contributors who have just" -" joined the project. Labeling issues in this way shows that the project is " -"prepared to onboard new contributors and that maintainers welcome community " -"assistance in a particular area. Don't be afraid to file issues against " -"project documentation, the website,or anything else you feel is amiss. If " -"there's a place current and potential contributors can help make the project" -" better, file these in your issue tracker with a clear label that shows them" -" they can contribute." +"maintainers to flag issues particularly suited to contributors who have " +"just joined the project. Labeling issues in this way shows that the " +"project is prepared to onboard new contributors and that maintainers " +"welcome community assistance in a particular area. Don't be afraid to " +"file issues against project documentation, the website,or anything else " +"you feel is amiss. If there's a place current and potential contributors " +"can help make the project better, file these in your issue tracker with a" +" clear label that shows them they can contribute." msgstr "将问题标记为“新手友好”或“寻求帮助”可以让项目维护者特别标注出适合新加入贡献者处理的问题。这种标记方式表明项目已准备好接纳新贡献者,且维护者欢迎社区在特定领域提供协助。不要害怕针对项目文档、网站或任何你认为有问题的地方提交问题。如果存在当前或潜在贡献者可以帮助改进项目的地方,就在问题跟踪器中提交这些问题,并贴上清晰的标签,让他们知道自己可以参与贡献。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:172 msgid "" -"Just make _very clear_ (either in the text of the \"help wanted\" issue or " -"via a link to other project documentation) how you wish others to engage " -"with the project when working on these types of issues. (The [Apache " -"Subversion Issues page](https://subversion.apache.org/reporting-issues.html)" -" is an excellent example of clearly articulating needs to the user community" -" before they file an issue.) It is best to encourage contributors working on" -" these issues to engage with the project maintainers along the way, so their" -" contributions have a higher chance of acceptance into the project. Nothing " -"squelches a contributor's enthusiasm like showing up with a working solution" -" to the stated problem only to be told their particular implementation will " -"not meet the project's needs." +"Just make _very clear_ (either in the text of the \"help wanted\" issue " +"or via a link to other project documentation) how you wish others to " +"engage with the project when working on these types of issues. (The " +"[Apache Subversion Issues page](https://subversion.apache.org/reporting-" +"issues.html) is an excellent example of clearly articulating needs to the" +" user community before they file an issue.) It is best to encourage " +"contributors working on these issues to engage with the project " +"maintainers along the way, so their contributions have a higher chance of" +" acceptance into the project. Nothing squelches a contributor's " +"enthusiasm like showing up with a working solution to the stated problem " +"only to be told their particular implementation will not meet the " +"project's needs." msgstr "" "只需_明确_说明(可以在“需要帮助”的问题文本中或通过链接到其他项目文档)你希望他人在处理此类问题时如何参与项目。([Apache " "Subversion问题页面](https://subversion.apache.org/reporting-" @@ -782,13 +795,14 @@ msgstr "清晰友善地沟通" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:176 msgid "" "Whether you are a user of the project reporting an issue or a project " -"maintainer reviewing a pull request, it is always important to communicate " -"about the issue _clearly_ and _kindly_. When a tool is not working, the " -"person using it can become frustrated. Likewise, a person developing a " -"project as a hobby is unlikely to respond well to demands on their time to " -"fix a problem they do not have. Remember to be gracious and thankful in your" -" discussions with other project participants, as everyone sharing their " -"knowledge is contributing to the project's overall health and wellbeing." +"maintainer reviewing a pull request, it is always important to " +"communicate about the issue _clearly_ and _kindly_. When a tool is not " +"working, the person using it can become frustrated. Likewise, a person " +"developing a project as a hobby is unlikely to respond well to demands on" +" their time to fix a problem they do not have. Remember to be gracious " +"and thankful in your discussions with other project participants, as " +"everyone sharing their knowledge is contributing to the project's overall" +" health and wellbeing." msgstr "无论你是报告问题的项目使用者,还是审查拉取请求的项目维护者,_清晰友善地_沟通问题始终至关重要。当工具无法正常工作时,使用者可能会感到沮丧。同样,将项目开发作为业余爱好的人,也不太可能对要求他们花时间解决与自己无关的问题作出积极回应。请记住在与项目其他参与者讨论时保持礼貌和感激,因为每个分享知识的人都在为项目的整体健康发展贡献力量。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:178 @@ -797,17 +811,17 @@ msgstr "当问题成为激烈辩论的焦点" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:180 msgid "" -"At times, the details of addressing a particular issue can cause tension or " -"arguments within the community." +"At times, the details of addressing a particular issue can cause tension " +"or arguments within the community." msgstr "有时,解决特定问题的细节可能会在社区内引发紧张或争论。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:182 msgid "" -"While healthy and respectful debate is part of any thriving project—software" -" or otherwise—tempers can flare easily, and as [has been well " -"documented](https://www.bbc.com/future/article/20180403-why-do-people-" -"become-trolls-online-and-in-social-media) people tend to behave with less " -"civility online than they would in person." +"While healthy and respectful debate is part of any thriving " +"project—software or otherwise—tempers can flare easily, and as [has been " +"well documented](https://www.bbc.com/future/article/20180403-why-do-" +"people-become-trolls-online-and-in-social-media) people tend to behave " +"with less civility online than they would in person." msgstr "" "在任何蓬勃发展的项目中——无论是软件还是其他领域——健康且相互尊重的辩论都是不可或缺的一部分,但情绪很容易升温,而且正如[大量记录所显示的](https://www.bbc.com/future/article/20180403" "-why-do-people-become-trolls-online-and-in-social-" @@ -815,10 +829,10 @@ msgstr "" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:184 msgid "" -"If an issue has become especially contentious and discourse has become rude " -"or inflammatory, restrict access to that issue for a stated period of time " -"(say 24 to 48 hours) to allow people time to calm down, reflect, and state " -"their argument in a more even-tempered and constructive manner." +"If an issue has become especially contentious and discourse has become " +"rude or inflammatory, restrict access to that issue for a stated period " +"of time (say 24 to 48 hours) to allow people time to calm down, reflect, " +"and state their argument in a more even-tempered and constructive manner." msgstr "" "若某个问题引发激烈争议且讨论变得粗鲁或煽动性,可限制该问题的访问权限一段时间(例如 24 至 48 " "小时),让人们有时间冷静思考,以更平和、建设性的方式阐述观点。" @@ -829,35 +843,36 @@ msgstr "提交问题的快速提示" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:188 msgid "" -"Thank the people creating the software for their time and energy, especially" -" if you are new to the project. The individuals spending their (spare) time " -"creating free and open source software for you to use are also people who " -"want to know their time is valued and their work appreciated." +"Thank the people creating the software for their time and energy, " +"especially if you are new to the project. The individuals spending their " +"(spare) time creating free and open source software for you to use are " +"also people who want to know their time is valued and their work " +"appreciated." msgstr "感谢那些投入时间和精力开发软件的人们,特别是当你刚接触这个项目时。这些利用(业余)时间为你创造免费开源软件的个体,同样渴望知道自己的时间被珍视、劳动成果被认可。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:190 msgid "" "Include as much information as you possibly can about the error you have " -"encountered. If the project uses issue templates, fill one out as completely" -" as possible." +"encountered. If the project uses issue templates, fill one out as " +"completely as possible." msgstr "尽可能详细地提供你遇到的错误信息。如果项目使用了问题模板,请尽可能完整地填写模板内容。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:192 msgid "" -"If you do not have the information requested or cannot determine how to get " -"it yourself, simply note what you have attempted to do in order to get the " -"information. These details help maintainers determine what they might need " -"to do to assist you." +"If you do not have the information requested or cannot determine how to " +"get it yourself, simply note what you have attempted to do in order to " +"get the information. These details help maintainers determine what they " +"might need to do to assist you." msgstr "若你无法提供所需信息或不确定如何自行获取,只需注明你已尝试过哪些方法。这些细节有助于维护者判断他们需要采取哪些措施来协助你。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:194 msgid "" -"If a project does not use issue templates, look at other issues that have " -"been \"closed‒fixed\" or at merged pull requests to see how other people " -"have filed bug reports. If the issue was fixed, chances are quite good that " -"you'll be able to use these historical artifacts as examples of the sort of " -"information necessary for reproducing an error. Replicate what you find in " -"these reports and add more detail as you are able." +"If a project does not use issue templates, look at other issues that have" +" been \"closed‒fixed\" or at merged pull requests to see how other people" +" have filed bug reports. If the issue was fixed, chances are quite good " +"that you'll be able to use these historical artifacts as examples of the " +"sort of information necessary for reproducing an error. Replicate what " +"you find in these reports and add more detail as you are able." msgstr "如果项目没有使用问题(issue)模板,可以查看其他已\"关闭-已修复\"的问题或已合并的拉取请求,了解他人是如何提交错误报告的。若该问题已被修复,那么这些历史记录很可能就能作为重现错误所需信息类型的范例。按照这些报告中的内容进行复现,并尽可能补充更多细节。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:196 @@ -866,12 +881,13 @@ msgstr "快速响应问题的技巧" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:198 msgid "" -"\"While the size and skill of the development community constrains the rate " -"at which tickets can be resolved, the project should at least try to " -"acknowledge each ticket the moment it appears. Even if the ticket lingers " -"for a while, a response encourages the reporter to stay involved, because " -"she feels that a human has registered what she has done (remember that " -"filing a ticket usually involves more effort than, say, posting an email).\"" +"\"While the size and skill of the development community constrains the " +"rate at which tickets can be resolved, the project should at least try to" +" acknowledge each ticket the moment it appears. Even if the ticket " +"lingers for a while, a response encourages the reporter to stay involved," +" because she feels that a human has registered what she has done " +"(remember that filing a ticket usually involves more effort than, say, " +"posting an email).\"" msgstr "“虽然开发社区的规模和技能限制了问题单的处理速度,但项目至少应在问题单出现时立即予以确认。即使问题单会滞留一段时间,及时回应也能鼓励提交者保持参与,因为她能感受到自己的付出已被人工记录(请记住,提交问题单通常比发送电子邮件需要更多精力)。”" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:200 @@ -880,64 +896,66 @@ msgstr "— Karl Fogel, Producing Open Source Software[^fogel-oss]" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:202 msgid "" -"Thank the submitter for filing the issue. Helping a project improve is an " -"excellent contribution to that project's health. Further, by being gracious," -" kind and welcoming, you encourage continued participation and contribution " -"from the issue reporter." +"Thank the submitter for filing the issue. Helping a project improve is an" +" excellent contribution to that project's health. Further, by being " +"gracious, kind and welcoming, you encourage continued participation and " +"contribution from the issue reporter." msgstr "感谢提交者提出问题。帮助项目改进是对项目健康的卓越贡献。此外,通过保持亲切、友善和热情的态度,你将鼓励问题报告者持续参与和贡献。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:204 msgid "" -"When closing an issue as \"won't fix,\" explain why the issue will not be " -"fixed. Maintainers shouldn't feel compelled to accept every pull request or " -"fix every reported issue, but they should at least let bug reporters know " -"_why_ they won't be addressing certain issues." +"When closing an issue as \"won't fix,\" explain why the issue will not be" +" fixed. Maintainers shouldn't feel compelled to accept every pull request" +" or fix every reported issue, but they should at least let bug reporters " +"know _why_ they won't be addressing certain issues." msgstr "当以“不予修复”关闭问题时,需说明不予修复的原因。维护者无需被迫接受每一个拉取请求或修复所有报告的问题,但至少应告知问题提交者_为何_某些问题不会被处理。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:206 msgid "" -"In particular, if someone has submitted an issue along with code to fix a " -"problem or implement a new feature, it is vital to tell them why their work " -"has not been accepted by the project. Not doing so makes the contributor " -"feel like they've wasted their time and should devote their energies to a " -"different software project. In an ideal world, you are able to include a " -"link to a published project roadmap that explains why the submission does " -"not meet the needs of the project. (Refer to above.)" +"In particular, if someone has submitted an issue along with code to fix a" +" problem or implement a new feature, it is vital to tell them why their " +"work has not been accepted by the project. Not doing so makes the " +"contributor feel like they've wasted their time and should devote their " +"energies to a different software project. In an ideal world, you are able" +" to include a link to a published project roadmap that explains why the " +"submission does not meet the needs of the project. (Refer to above.)" msgstr "特别是当有人提交了问题报告及修复代码或新功能实现时,务必向其说明为何其工作成果未被项目采纳。若不作解释,贡献者会感到自己的时间被浪费,进而将精力转向其他软件项目。理想情况下,你应当附上已发布的项目路线图链接,阐明该提交为何不符合项目需求。(参见上文说明。)" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:208 msgid "" -"For new contributor submissions, fix minor issues with the patch yourself " -"along with a note about what you fixed and why. Having a patch rejected for " -"minor nits discourages additional contribution, and often it takes just as " -"long to explain why a patch is being rejected as it does to make very small " -"fixes. Such explanations are an excellent time to point contributors to " -"additional project resources, such as your coding style guide, documentation" -" on communication norms, etc." +"For new contributor submissions, fix minor issues with the patch yourself" +" along with a note about what you fixed and why. Having a patch rejected " +"for minor nits discourages additional contribution, and often it takes " +"just as long to explain why a patch is being rejected as it does to make " +"very small fixes. Such explanations are an excellent time to point " +"contributors to additional project resources, such as your coding style " +"guide, documentation on communication norms, etc." msgstr "对于新贡献者提交的内容,你可以自行修复补丁中的小问题,并附上说明解释修复内容和原因。因细微瑕疵而拒绝补丁会打击贡献积极性,且解释拒绝原因所花的时间往往与进行微小修复相当。这类解释是引导贡献者查阅项目其他资源(如代码风格指南、沟通规范文档等)的绝佳时机。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:210 msgid "" -"For submissions coming in response to a \"help wanted\" issue, engage early " -"and often with the person who has stated an interest in working on the " -"issue. Doing so ensures that the contributor's submission will actually meet" -" the project's needs. Further, by being available to and in regular dialogue" -" with new contributors, you form a relationship with them that encourages " -"mutual learning and increases the chances they will continue to contribute " -"to the project's ongoing work." +"For submissions coming in response to a \"help wanted\" issue, engage " +"early and often with the person who has stated an interest in working on " +"the issue. Doing so ensures that the contributor's submission will " +"actually meet the project's needs. Further, by being available to and in " +"regular dialogue with new contributors, you form a relationship with them" +" that encourages mutual learning and increases the chances they will " +"continue to contribute to the project's ongoing work." msgstr "对于响应\"求助\"问题提交的内容,需尽早且频繁地与表示有兴趣处理该问题的人员进行沟通。这样做能确保贡献者的提交真正符合项目需求。此外,通过保持对新贡献者的可及性和定期对话,你将与他们建立一种促进相互学习的关系,并增加他们持续参与项目后续工作的可能性。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:212 -msgid "Having development discussions and other conversations in the issue tracker" +msgid "" +"Having development discussions and other conversations in the issue " +"tracker" msgstr "在问题跟踪系统中进行开发讨论和其他对话" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:214 msgid "" -"Conventional wisdom in the early days of open source software development " -"held that communities should _not_ carry on development related discussions " -"in the project's issue tracker. Project communities instead preferred " -"carrying on such conversations via mailing lists or in forums for a number " -"of reasons:" +"Conventional wisdom in the early days of open source software development" +" held that communities should _not_ carry on development related " +"discussions in the project's issue tracker. Project communities instead " +"preferred carrying on such conversations via mailing lists or in forums " +"for a number of reasons:" msgstr "开源软件开发早期的传统观点认为,社区_不应_在项目的问题跟踪器中进行开发相关讨论。项目社区更倾向于通过邮件列表或论坛开展此类对话,原因包括:" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:216 @@ -948,35 +966,36 @@ msgstr "订阅邮件列表的人员无需解析问题跟踪器内容即可发表 #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:217 msgid "" -"Forum or mailing list conversations were seen as better for asynchronous and" -" long-form communications, and popular issue trackers in the 1990s and early" -" 2000s were an unwieldy way to engage in actual discourse." +"Forum or mailing list conversations were seen as better for asynchronous " +"and long-form communications, and popular issue trackers in the 1990s and" +" early 2000s were an unwieldy way to engage in actual discourse." msgstr "论坛或邮件列表对话被认为更适合异步和长篇交流,而 1990 年代至 2000 年代初流行的问题跟踪工具并不适合开展实质性讨论" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:218 msgid "" -"Discovering why a particular technical decision was made when those details " -"were buried in an issue tracker was difficult, especially since the issue " -"would be in a \"closed\" state once the decision was made. Looking for a " -"closed issue to explain the technical direction of the project was " -"considered counterintuitive." +"Discovering why a particular technical decision was made when those " +"details were buried in an issue tracker was difficult, especially since " +"the issue would be in a \"closed\" state once the decision was made. " +"Looking for a closed issue to explain the technical direction of the " +"project was considered counterintuitive." msgstr "要查明某项技术决策的具体原因十分困难,因为这些细节往往埋没在问题追踪系统中,尤其当决策完成后相关问题会被标记为\"已关闭\"状态。在已关闭的问题中寻找项目技术方向的解释,这种操作方式本身就违背常理。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:220 msgid "" "With the rise in popularity of GitHub as a one-stop platform for online " "development work, conversations in the project issue tracker have become " -"mainstream. GitHub's issue system visually mirrors the typically expected " -"visual interface for forum software, making discussions in its system seem " -"natural for those who began their development careers when online forums " -"were first gaining popularity. Further, time and resources necessary for " -"maintaining a Mailman instance or additional forum software as part of " -"project infrastructure became cumbersome when all other infrastructure could" -" be managed via a single tool. The addition of features such as the ability " -"to \"+1\" an issue, set fine-grained controls on notifications for specific " -"issues, and lock specific issues so that only project maintainers may edit " -"it (while still allowing others to view the issue) made the move to " -"discussions in the issue tracker more palatable and effective." +"mainstream. GitHub's issue system visually mirrors the typically expected" +" visual interface for forum software, making discussions in its system " +"seem natural for those who began their development careers when online " +"forums were first gaining popularity. Further, time and resources " +"necessary for maintaining a Mailman instance or additional forum software" +" as part of project infrastructure became cumbersome when all other " +"infrastructure could be managed via a single tool. The addition of " +"features such as the ability to \"+1\" an issue, set fine-grained " +"controls on notifications for specific issues, and lock specific issues " +"so that only project maintainers may edit it (while still allowing others" +" to view the issue) made the move to discussions in the issue tracker " +"more palatable and effective." msgstr "" "随着 GitHub 作为一站式在线开发平台的兴起,项目问题追踪器中的讨论已成为主流。GitHub " "的问题系统在视觉上复现了论坛软件常见的界面形态,这让在其系统中进行的讨论对成长于网络论坛兴起时代的开发者而言显得尤为自然。此外,当所有基础设施都能通过单一工具管理时,维护" @@ -986,16 +1005,17 @@ msgstr "" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:222 msgid "" "Nonetheless, interested parties should be able to follow discussions " -"_outside_ the project's issue tracker. Only the most deeply interested and " -"invested individuals will rigorously follow every issue update, making " -"engaging with the project difficult for casual contributors. While excellent" -" search capabilities in online issue trackers make finding closed issues " -"easier, the flow of an issue discussion does not fulfill the same function " -"as a narrative description of a particular implementation or an explanation " -"of why a certain decision was made. Note, too, that some maintainers who are" -" most intimately familiar with the project—those who can recall specific " -"issue numbers for particular discussions with ease—will not always be " -"available to help with the project work." +"_outside_ the project's issue tracker. Only the most deeply interested " +"and invested individuals will rigorously follow every issue update, " +"making engaging with the project difficult for casual contributors. While" +" excellent search capabilities in online issue trackers make finding " +"closed issues easier, the flow of an issue discussion does not fulfill " +"the same function as a narrative description of a particular " +"implementation or an explanation of why a certain decision was made. " +"Note, too, that some maintainers who are most intimately familiar with " +"the project—those who can recall specific issue numbers for particular " +"discussions with ease—will not always be available to help with the " +"project work." msgstr "然而,项目外部人士也应能跟进讨论内容。只有极少数深度投入的参与者会严格追踪每个问题更新,这使得临时贡献者难以参与项目。虽然在线问题追踪系统强大的搜索功能让查找已关闭问题更为便捷,但问题讨论的流程并不能替代对具体实施方案的叙述性说明,或对某项决策原因的阐释。还需注意的是,那些对项目最为熟悉(能轻易回忆起特定讨论对应问题编号)的维护者们,并非总能随时协助项目工作。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:224 @@ -1012,33 +1032,31 @@ msgstr "节省维护者的时间,使他们无需定期重复讲解历史背景 #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:228 msgid "" -"Ensures that critical details on how and why decisions were made are always " -"available even as project membership changes." +"Ensures that critical details on how and why decisions were made are " +"always available even as project membership changes." msgstr "确保即使项目成员发生变化,关键决策的制定方式及原因也始终清晰可查。" -#: ../../attracting-users/communication-norms-in-open-source-software-projects.md:230 +#: ../../attracting-users/communication-norms-in-open-source-software-projects.md:231 #, python-brace-format, python-format msgid "" -"{% hint style=\"success\" %} If your project carries on most of its " -"development discussions in the issue tracker, consider taking some small " -"steps to highlight these discussions in other ways that will be most " -"accessible and discoverable to interested parties and wider audiences in " -"general. {% endhint %}" +"If your project carries on most of its development discussions in the " +"issue tracker, consider taking some small steps to highlight these " +"discussions in other ways that will be most accessible and discoverable " +"to interested parties and wider audiences in general." msgstr "" -"{% hint style=\"success\" %} " -"如果项目的大部分开发讨论都在问题跟踪器中进行,可以考虑采取一些小措施,以更易于相关方和广大受众发现和获取的方式,在其他渠道突出展示这些讨论。 {% " -"endhint %}" +"如果项目的大部分开发讨论都在问题跟踪器中进行,可以考虑采取一些小措施,以更易于相关方和广大受众发现和获取的方式,在其他渠道突出展示这些讨论。 {%" +" endhint %}" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:234 msgid "" -"For example, you may summarize the discussion of the issue in a blog, forum " -"post, or project newsletter, thereby preserving cultural lore for the " -"project while simultaneously informing the broader community about the " -"change. If the project does not maintain a blog or other publication " +"For example, you may summarize the discussion of the issue in a blog, " +"forum post, or project newsletter, thereby preserving cultural lore for " +"the project while simultaneously informing the broader community about " +"the change. If the project does not maintain a blog or other publication " "mechanism suitable for such a communication, consider adding a list of " "watershed issues to your project documentation so newcomers can quickly " -"become familiar with these critical topics, and for ease of reference for " -"long-time project participants." +"become familiar with these critical topics, and for ease of reference for" +" long-time project participants." msgstr "例如,你可以在博客、论坛帖子或项目通讯中总结该问题的讨论,这样既能保存项目的文化传承,又能向更广泛的社区通报变更。如果项目没有维护博客或其他适合此类沟通的发布机制,可以考虑在项目文档中添加关键问题列表,以便新人能快速了解这些重要主题,同时也便于长期项目参与者随时查阅。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:236 @@ -1051,13 +1069,13 @@ msgstr "英语作为互联网的通用语言" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:240 msgid "" -"Though we live in a world where more than 6,500 languages are spoken, for " -"historical reasons the primary language used for communicating on the " -"Internet—and therefore, in major open source projects—is English. For users " -"and contributors who are not native English speakers, this fact can raise " -"significant barriers to participation. There are a few steps projects can " -"take to help those for whom English is not their first language to more " -"effectively participate in the project." +"Though we live in a world where more than 6,500 languages are spoken, for" +" historical reasons the primary language used for communicating on the " +"Internet—and therefore, in major open source projects—is English. For " +"users and contributors who are not native English speakers, this fact can" +" raise significant barriers to participation. There are a few steps " +"projects can take to help those for whom English is not their first " +"language to more effectively participate in the project." msgstr "" "尽管我们生活在一个使用超过 6500 " "种语言的世界里,但由于历史原因,互联网交流——以及主要开源项目中使用的主要语言仍是英语。对于非英语母语用户和贡献者而言,这一事实会形成显著的参与障碍。项目方可以采取若干措施来帮助非英语母语者更有效地参与项目。" @@ -1068,23 +1086,23 @@ msgstr "显著标注多语言社区资源" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:244 msgid "" -"Should your project be widely adopted and grow to the point that it hosts " -"communication channels in more than one language, make sure to list these " -"resources prominently on your project's website. Include on the project's " -"website a note that the project welcomes submissions from community members " -"for resources that are not written in English. When the project receives " -"such submissions act promptly to get them included in your project " -"documentation." +"Should your project be widely adopted and grow to the point that it hosts" +" communication channels in more than one language, make sure to list " +"these resources prominently on your project's website. Include on the " +"project's website a note that the project welcomes submissions from " +"community members for resources that are not written in English. When the" +" project receives such submissions act promptly to get them included in " +"your project documentation." msgstr "如果你的项目被广泛采用并发展到拥有多种语言交流渠道的程度,请确保在项目网站上显著列出这些资源。在项目网站上注明:项目欢迎社区成员提交非英语撰写的资源。当项目收到此类提交时,请及时将其纳入项目文档中。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:246 msgid "" -"As you would with any resource you point your community to, do your best to " -"ensure the resource is helpful. If you are unable to vet the resources as " -"helpful given currently available person-hours on the project, reference the" -" fact that project maintainers have been unable to assess the resource " -"themselves. Note you welcome feedback on its inclusion in the project's " -"documentation." +"As you would with any resource you point your community to, do your best " +"to ensure the resource is helpful. If you are unable to vet the resources" +" as helpful given currently available person-hours on the project, " +"reference the fact that project maintainers have been unable to assess " +"the resource themselves. Note you welcome feedback on its inclusion in " +"the project's documentation." msgstr "正如你向社区推荐任何资源时一样,请尽力确保该资源具有实用性。若项目当前可用人力无法验证资源的价值,请说明项目维护者尚未能亲自评估该资源的情况,同时表明欢迎社区对其纳入项目文档提出反馈意见。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:248 @@ -1093,31 +1111,29 @@ msgstr "无论英语水平如何 都应友善相待" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:250 msgid "" -"As this chapter has stressed numerous times, kind and gracious communication" -" with all those who participate in your project should be a default mode of " -"behavior for interactions. The same holds true when communicating with " -"people for whom writing in English is difficult. If you have trouble " -"understanding what someone is saying or asking for, ask clarifying questions" -" to let them know you will be happy to help them. Don't simply ignore " -"someone or tell them they are not welcome in the project due to limited " -"proficiency in written English." +"As this chapter has stressed numerous times, kind and gracious " +"communication with all those who participate in your project should be a " +"default mode of behavior for interactions. The same holds true when " +"communicating with people for whom writing in English is difficult. If " +"you have trouble understanding what someone is saying or asking for, ask " +"clarifying questions to let them know you will be happy to help them. " +"Don't simply ignore someone or tell them they are not welcome in the " +"project due to limited proficiency in written English." msgstr "正如本章多次强调的那样,与所有项目参与者保持友善、得体的沟通应成为互动的默认行为准则。当与那些用英语表达存在困难的人交流时,同样需要遵循这一原则。如果难以理解对方的表述或需求,应通过提问澄清来表明你乐意提供帮助。切勿仅因对方书面英语水平有限就忽视其存在,或宣称其在项目中不受欢迎。" -#: ../../attracting-users/communication-norms-in-open-source-software-projects.md:252 +#: ../../attracting-users/communication-norms-in-open-source-software-projects.md:253 #, python-brace-format, python-format msgid "" -"{% hint style=\"success\" %} People who are not native speakers of English " -"often begin their communication with the project with an apology for their " -"poor English language skills. When receiving such a communication, thank the" -" sender for writing and let them know you appreciate their efforts to " -"communicate with the project. Where possible, point them to any resources " -"that may be available to them in a language with which they are more " -"familiar, for example a Spanish language forum or a Chinese language mailing" -" list for the project. {% endhint %}" +"People who are not native speakers of English often begin their " +"communication with the project with an apology for their poor English " +"language skills. When receiving such a communication, thank the sender " +"for writing and let them know you appreciate their efforts to communicate" +" with the project. Where possible, point them to any resources that may " +"be available to them in a language with which they are more familiar, for" +" example a Spanish language forum or a Chinese language mailing list for " +"the project." msgstr "" -"{% hint style=\"success\" %} " "非英语母语者在与项目沟通时,常会因英语水平欠佳而先致歉。收到此类信息时,请感谢对方的来信,并表达对其努力与项目沟通的赞赏。如有可能,可引导他们获取更熟悉的语言资源,例如项目的西班牙语论坛或中文邮件列表。" -" {% endhint %}" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:256 msgid "Avoid idioms in written documentation" @@ -1126,13 +1142,13 @@ msgstr "在书面文档中避免使用习语" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:258 msgid "" "Every language features various phrases the actual words of which do not " -"convey the intended meaning of the phrase, such as \"over the moon\" to mean" -" extremely happy or excited or \"raining cats and dogs\" to refer to a " -"serious downpour of rain. For those who grow up in a particular culture, the" -" meanings of these phrases are obvious. But they can be confusing for those " -"who lack the proper context for them. Rather than rely on idiomatic phrases," -" use plain language in written documentation to ensure the writing is most " -"accessible to all people." +"convey the intended meaning of the phrase, such as \"over the moon\" to " +"mean extremely happy or excited or \"raining cats and dogs\" to refer to " +"a serious downpour of rain. For those who grow up in a particular " +"culture, the meanings of these phrases are obvious. But they can be " +"confusing for those who lack the proper context for them. Rather than " +"rely on idiomatic phrases, use plain language in written documentation to" +" ensure the writing is most accessible to all people." msgstr "" "每种语言都包含一些字面意思与实际含义不符的短语,比如用\"over the moon\"表示极度开心,或用\"raining cats and " "dogs\"形容倾盆大雨。对特定文化背景的人而言,这些短语的含义显而易见。但缺乏相关语境的人可能会感到困惑。为确保文档对所有读者都清晰易懂,请使用平实的语言替代习语表达。" @@ -1143,17 +1159,17 @@ msgstr "展开缩略词并提供术语表" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:262 msgid "" -"While acronyms are a useful way for those completely familiar with a topic " -"to save time and effort typing and speaking longer phrases, they obfuscate " -"information for those less familiar with the topic. Further, acronyms are " -"often overloaded, meaning that the acronym can expand several different ways" -" depending upon the topic area. For example, someone completely new to a " -"project may not understand that \"LGTM\" means \"looks good to me\" and that" -" their work is therefore acceptable for merging into the project's source " -"repository. If you regularly use particular acronyms as part of " -"communicating in your project, take the time to create a quick glossary of " -"these terms. Updating this glossary is a quick and easy way for volunteers " -"to contribute." +"While acronyms are a useful way for those completely familiar with a " +"topic to save time and effort typing and speaking longer phrases, they " +"obfuscate information for those less familiar with the topic. Further, " +"acronyms are often overloaded, meaning that the acronym can expand " +"several different ways depending upon the topic area. For example, " +"someone completely new to a project may not understand that \"LGTM\" " +"means \"looks good to me\" and that their work is therefore acceptable " +"for merging into the project's source repository. If you regularly use " +"particular acronyms as part of communicating in your project, take the " +"time to create a quick glossary of these terms. Updating this glossary is" +" a quick and easy way for volunteers to contribute." msgstr "" "虽然缩略词能让熟悉某领域的人省时省力,免去输入或说出完整短语的麻烦,但它们却会让不熟悉该领域的人感到困惑。此外,缩略词往往存在多义性,即同一个缩略词在不同领域可能对应不同的全称。例如,刚接触某个项目的新人可能不明白\"LGTM\"表示\"looks" " good to " @@ -1165,14 +1181,15 @@ msgstr "积极寻求本地化志愿者的参与" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:266 msgid "" -"As mentioned earlier in this chapter, project maintainers should always be " -"clear about _what kind of help_ they're seeking from their communities. One " -"key area in which to ask for help is the localization of documentation " -"resources. Regardless of their skill level with software development " -"practices, community members can actively grow the project and improve it by" -" translating documentation, thereby making the project more accessible to " -"more people and more potential contributors. Maintainers should be explicit " -"about their desire to recruit contributors focused on localization." +"As mentioned earlier in this chapter, project maintainers should always " +"be clear about _what kind of help_ they're seeking from their " +"communities. One key area in which to ask for help is the localization of" +" documentation resources. Regardless of their skill level with software " +"development practices, community members can actively grow the project " +"and improve it by translating documentation, thereby making the project " +"more accessible to more people and more potential contributors. " +"Maintainers should be explicit about their desire to recruit contributors" +" focused on localization." msgstr "正如本章前面提到的,项目维护者应当始终明确他们希望从社区获得何种帮助。文档资源的本地化就是一个关键的需求领域。无论社区成员的软件开发技能水平如何,他们都可以通过翻译文档来积极推动项目发展并提升质量,从而使项目能够触达更多人群和潜在贡献者。维护者应当明确表达招募专注于本地化工作的贡献者的意愿。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:268 @@ -1182,25 +1199,25 @@ msgstr "记录项目的沟通规范" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:270 msgid "" "When people approach a new project, they seek to understand how they can " -"best engage with that project and interact with its community. Be sure your " -"documentation clearly outlines your project's various communication " +"best engage with that project and interact with its community. Be sure " +"your documentation clearly outlines your project's various communication " "channels." msgstr "当人们接触一个新项目时,他们希望了解如何才能最好地参与该项目并与社区互动。请确保你的文档清晰地列出项目的各种沟通渠道。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:272 msgid "" "Simply _listing_ communication channels is not sufficient. Your " -"documentation must make clear _what_ each channel is used for, _when_ to use" -" a particular communication mechanism, and _how_ people can expect to " -"receive communications from the project and its community members through " -"that channel. For example, a project with few maintainers who develop the " -"work as a hobby project may wish to note on the project website that those " -"developing the project do so in their spare time, so immediate responses to " -"mailing list inquiries should not be expected. Someone whose hobby project " -"is in use with enterprises might like to make explicit the notion that help " -"is provided on a best effort basis. (Doing so sets expectations " -"appropriately for those who are less familiar with how open source project " -"communities function.)" +"documentation must make clear _what_ each channel is used for, _when_ to " +"use a particular communication mechanism, and _how_ people can expect to " +"receive communications from the project and its community members through" +" that channel. For example, a project with few maintainers who develop " +"the work as a hobby project may wish to note on the project website that " +"those developing the project do so in their spare time, so immediate " +"responses to mailing list inquiries should not be expected. Someone whose" +" hobby project is in use with enterprises might like to make explicit the" +" notion that help is provided on a best effort basis. (Doing so sets " +"expectations appropriately for those who are less familiar with how open " +"source project communities function.)" msgstr "仅仅_列出_沟通渠道是不够的。你的文档必须明确说明_每个渠道的用途_、_何时使用特定沟通机制_,以及人们可以期待如何_通过该渠道接收来自项目及其社区成员的沟通信息_。例如,一个由少数维护者作为业余爱好开发的项目,可能希望在项目网站上注明开发者是利用业余时间进行工作的,因此不应期待对邮件列表咨询的即时回复。若某人的业余项目被企业使用,则可能需要明确说明帮助仅基于最大努力原则提供(这样做可以为那些不太熟悉开源项目社区运作方式的人设定合理的期望)。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:274 @@ -1209,16 +1226,17 @@ msgstr "保持文明对话" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:276 msgid "" -"As has been discussed throughout this chapter, maintaining kind and gracious" -" communications is vital for the project's ongoing health and well-being. " -"While assuming everyone understands what \"kind and gracious communication\"" -" looks like may seem natural, one cannot assume a consistent meaning for all" -" participants, especially when dealing with a global audience. Project " -"maintainers and community members do well to lead by example. But it sets an" -" appropriate tone for the project to make an explicit statement about what " -"constitutes civil discourse, what matters are off-topic for the project, and" -" what is expected from anyone communicating with the project, especially " -"about matters that may cause conflict ." +"As has been discussed throughout this chapter, maintaining kind and " +"gracious communications is vital for the project's ongoing health and " +"well-being. While assuming everyone understands what \"kind and gracious " +"communication\" looks like may seem natural, one cannot assume a " +"consistent meaning for all participants, especially when dealing with a " +"global audience. Project maintainers and community members do well to " +"lead by example. But it sets an appropriate tone for the project to make " +"an explicit statement about what constitutes civil discourse, what " +"matters are off-topic for the project, and what is expected from anyone " +"communicating with the project, especially about matters that may cause " +"conflict ." msgstr "正如本章通篇所讨论的,保持友善与得体的沟通对项目的持续健康发展至关重要。虽然人们可能自然而然地认为每个人都理解\"友善与得体的沟通\"是什么样子,但我们不能假定所有参与者对此有一致的理解,尤其是在面对全球受众时。项目维护者和社区成员以身作则固然重要,但明确阐述何为文明讨论、哪些内容与项目无关、以及项目对沟通者(尤其是涉及可能引发争议的事项时)的期望,能为项目设定恰当的基调。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:278 @@ -1229,19 +1247,20 @@ msgstr "摘录自[Dreamwidth项目多样性声明](https://www.dreamwidth.org/le #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:280 msgid "" -"\"We welcome people of any gender identity or expression, race, ethnicity, " -"size, nationality, sexual orientation, ability level, neurotype, religion, " -"elder status, family structure, culture, subculture, political opinion, " -"identity, and self-identification. We welcome activists, artists, bloggers, " -"crafters, dilettantes, musicians, photographers, readers, writers, ordinary " -"people, extraordinary people, and everyone in between. We welcome people who" -" want to change the world, people who want to keep in touch with friends, " -"people who want to make great art, and people who just need a break after " -"work. We welcome fans, geeks, nerds, and pixel-stained technopeasant " -"wretches. (We welcome Internet beginners who aren't sure what any of those " -"terms refer to.) We welcome you no matter if the Internet was a household " -"word by the time you started secondary school or whether you were already " -"retired by the time the World Wide Web was invented." +"\"We welcome people of any gender identity or expression, race, " +"ethnicity, size, nationality, sexual orientation, ability level, " +"neurotype, religion, elder status, family structure, culture, subculture," +" political opinion, identity, and self-identification. We welcome " +"activists, artists, bloggers, crafters, dilettantes, musicians, " +"photographers, readers, writers, ordinary people, extraordinary people, " +"and everyone in between. We welcome people who want to change the world, " +"people who want to keep in touch with friends, people who want to make " +"great art, and people who just need a break after work. We welcome fans, " +"geeks, nerds, and pixel-stained technopeasant wretches. (We welcome " +"Internet beginners who aren't sure what any of those terms refer to.) We " +"welcome you no matter if the Internet was a household word by the time " +"you started secondary school or whether you were already retired by the " +"time the World Wide Web was invented." msgstr "我们欢迎任何性别认同或表达、种族、民族、体型、国籍、性取向、能力水平、神经类型、宗教信仰、长者身份、家庭结构、文化背景、亚文化群体、政治观点、身份认同与自我定义的人。我们欢迎社会活动家、艺术家、博主、手工艺人、文艺爱好者、音乐家、摄影师、阅读者、写作者、平凡人与非凡者,以及介于其间的所有人。我们欢迎想改变世界的人,想与朋友保持联系的人,想创作伟大艺术作品的人,以及仅仅需要工作后放松的人。我们欢迎爱好者、极客、书呆子和卷流量的IT民工挂逼。(我们也欢迎那些不确定这些黑话含义的互联网新手。)无论你上中学时互联网是否已家喻户晓,抑或万维网诞生时你早已退休——我们都欢迎你的加入。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:282 @@ -1250,30 +1269,31 @@ msgstr "...." #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:284 msgid "" -"We have enough experience to know that we won't get any of this perfect on " -"the first try. But we have enough hope, energy, and idealism to want to " -"learn things we don't know now. We may not be able to satisfy everyone, but " -"we can certainly work to avoid offending anyone. And we promise that if we " -"get it wrong, we'll listen carefully and respectfully to you when you point " -"it out to us, and we'll do our best to make good on our mistakes.\"" +"We have enough experience to know that we won't get any of this perfect " +"on the first try. But we have enough hope, energy, and idealism to want " +"to learn things we don't know now. We may not be able to satisfy " +"everyone, but we can certainly work to avoid offending anyone. And we " +"promise that if we get it wrong, we'll listen carefully and respectfully " +"to you when you point it out to us, and we'll do our best to make good on" +" our mistakes.\"" msgstr "通过实践积累的经验让我们深知,任何尝试都难以在初次就臻于完美。但我们仍怀揣着希望、热忱与理想主义精神,渴望不断汲取新知。虽然无法令所有人满意,但我们必定竭力避免冒犯任何群体。我们郑重承诺:若存在疏漏,当你指出时,我们将以谦逊姿态认真倾听,并全力以赴纠正过失。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:286 msgid "" -"This excerpt from the Diversity Statement of the Dreamwidth project is an " -"excellent example of how to document project communication norms. It is " +"This excerpt from the Diversity Statement of the Dreamwidth project is an" +" excellent example of how to document project communication norms. It is " "clear that everyone is welcome in the project, regardless of personal " -"background, technical skill level, or focus for using the project. It makes " -"it clear that mistakes will be made and that people are expected to use " -"these imperfections as learning opportunities, not excuses to belittle other" -" people. The statement tells users and would-be contributors that they may " -"not always get what they want from the project maintainers, but that errors " -"will be fixed and reasonable requests will be listened to, if not acted " -"upon. Most notably, it's a list of expected _prosocial behaviors_ rather " -"than simply a list of what _not to do_. It identifies behavior the project " -"maintainers and community members model and transforms it from the actions " -"they take into words that help everyone understand what actions constitute " -"good project citizenship." +"background, technical skill level, or focus for using the project. It " +"makes it clear that mistakes will be made and that people are expected to" +" use these imperfections as learning opportunities, not excuses to " +"belittle other people. The statement tells users and would-be " +"contributors that they may not always get what they want from the project" +" maintainers, but that errors will be fixed and reasonable requests will " +"be listened to, if not acted upon. Most notably, it's a list of expected " +"_prosocial behaviors_ rather than simply a list of what _not to do_. It " +"identifies behavior the project maintainers and community members model " +"and transforms it from the actions they take into words that help " +"everyone understand what actions constitute good project citizenship." msgstr "" "这段摘录自 Dreamwidth " "项目的《多样性声明》,堪称记录项目沟通规范的绝佳范例。它明确表示无论个人背景、技术水平或使用项目的侧重点如何,所有人都能在此项目中受到欢迎。声明清晰地指出犯错在所难免,并期望人们将这些不完美视为学习机会,而非贬低他人的借口。该声明告知用户及潜在贡献者:他们或许无法总是从项目维护者那里获得想要的东西,但错误会被修正,合理请求即使未被采纳也会得到倾听。尤为可贵的是,它列出的是一系列预期的_亲社会行为_,而非简单的_禁止事项_清单。声明将项目维护者和社区成员示范的行为,从具体行动转化为文字表述,帮助所有人理解哪些行为构成了优秀的项目公民素养。" @@ -1286,20 +1306,20 @@ msgstr "制定项目社会契约" msgid "" "As projects document their community communication norms, they may find " "developing a project social contract to be a particularly effective " -"exercise. A project social contract documents behaviors the project expects " -"all participants to display and sets expectations for how project members " -"will be accountable to others. The social contract is not necessarily a list" -" of forbidden behaviors, but rather a statement about how members of the " -"project will choose to self-govern for everyone's success. By undertaking " -"the process of creating a social contract through dialogue, members " -"establish empathy with one another and set the foundation for future " -"conversations." +"exercise. A project social contract documents behaviors the project " +"expects all participants to display and sets expectations for how project" +" members will be accountable to others. The social contract is not " +"necessarily a list of forbidden behaviors, but rather a statement about " +"how members of the project will choose to self-govern for everyone's " +"success. By undertaking the process of creating a social contract through" +" dialogue, members establish empathy with one another and set the " +"foundation for future conversations." msgstr "当项目记录其社区沟通规范时,制定项目社会契约可能特别有效。项目社会契约明确了项目期望所有参与者展现的行为,并设定了项目成员对他人负责的标准。这份契约本质上并非禁止行为清单,而是关于项目成员如何选择自我管理以实现共同成功的宣言。通过对话制定社会契约的过程,成员间建立起相互理解,为未来对话奠定基础。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:292 msgid "" -"You can learn more about creating social contracts, including tips for doing" -" so for remote teams, in [The Open Practice " +"You can learn more about creating social contracts, including tips for " +"doing so for remote teams, in [The Open Practice " "Library](https://openpracticelibrary.com/practice/social-contract/)." msgstr "" "你可以在[开放实践库](https://openpracticelibrary.com/practice/social-" @@ -1313,22 +1333,23 @@ msgstr "行为准则" msgid "" "Some projects use a code of conduct as a means to document their " "expectations around civil discourse. Open source projects that seek any " -"outside contribution should always have a code of conduct. For projects that" -" host events, whether virtual or in person, developing code of conduct " -"specific language around events is also a best practice. Think of the code " -"of conduct as an aspect of the project's social contract, one that includes " -"the rules by which the community will govern itself and how each member will" -" hold one another accountable for those moments when they could have behaved" -" differently and achieved a better outcome. These rules must be understood " -"and made explicit. Otherwise people will know neither what is expected of " -"them nor whether the project is a place where they will feel welcome and " -"comfortable contributing their time and expertise." +"outside contribution should always have a code of conduct. For projects " +"that host events, whether virtual or in person, developing code of " +"conduct specific language around events is also a best practice. Think of" +" the code of conduct as an aspect of the project's social contract, one " +"that includes the rules by which the community will govern itself and how" +" each member will hold one another accountable for those moments when " +"they could have behaved differently and achieved a better outcome. These " +"rules must be understood and made explicit. Otherwise people will know " +"neither what is expected of them nor whether the project is a place where" +" they will feel welcome and comfortable contributing their time and " +"expertise." msgstr "一些项目采用行为准则来记录他们对文明讨论的期望。寻求外部贡献的开源项目都应制定行为准则。对于举办线上或线下活动的项目而言,为活动制定专门的行为准则也是最佳实践。不妨将行为准则视为项目社会契约的一部分——它既包含社区自治的规则,也明确了每位成员如何在可能采取不同行动以获得更好结果时彼此问责。这些规则必须被明确理解和阐述,否则人们既不知道对他们的期望,也无法判断这个项目是否值得投入时间和专业知识。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:298 msgid "" -"Refer to this guidebook's chapter on governance for more information about " -"codes of conduct." +"Refer to this guidebook's chapter on governance for more information " +"about codes of conduct." msgstr "请参阅本指南书中关于治理的章节,以获取更多关于行为准则的信息。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:300 @@ -1339,45 +1360,47 @@ msgstr "与开源项目成功沟通" msgid "" "So far, we've focused primarily on ways in which software project " "_maintainers_ can ensure the best possible outcomes for communication in " -"their projects. However, contributors, too, can take a number of steps to " -"ensure they're communicating effectively with their favorite open source " -"communities. Here are just a few:" +"their projects. However, contributors, too, can take a number of steps to" +" ensure they're communicating effectively with their favorite open source" +" communities. Here are just a few:" msgstr "迄今为止,我们主要关注了软件项目维护者如何确保项目沟通获得最佳效果。然而,贡献者同样可以采取多项措施,确保与他们钟爱的开源社区进行有效沟通。以下列举几项建议:" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:304 msgid "" "**Read the project website and documentation before jumping into " -"discussions.**. Take the time to read about the project and understand its " -"nuances. Demonstrate that you respect the time and attention of the people " -"producing the project." +"discussions.**. Take the time to read about the project and understand " +"its nuances. Demonstrate that you respect the time and attention of the " +"people producing the project." msgstr "**在参与讨论前,先阅读项目官网和文档**。花时间了解项目详情并理解其细微差别。这表明你尊重项目贡献者的时间和专注力。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:305 msgid "" "**Do your research, and tell people you've done it.** If you run into a " "problem using open source software, do what you can to solve the problem " -"yourself. There's no shame in not being able to solve the problem, and it " -"helps your bug report. Make sure to include what steps you have taken to " -"resolve the issue when filing a bug report or asking for help in one of the " -"project's communication channels. Doing so saves people time and energy, as " -"they will not ask you to try something you have already done. Listing the " -"ways you've already attempted to help yourself is a demonstration of respect" -" for the time and energy of the project's maintainers." +"yourself. There's no shame in not being able to solve the problem, and it" +" helps your bug report. Make sure to include what steps you have taken to" +" resolve the issue when filing a bug report or asking for help in one of " +"the project's communication channels. Doing so saves people time and " +"energy, as they will not ask you to try something you have already done. " +"Listing the ways you've already attempted to help yourself is a " +"demonstration of respect for the time and energy of the project's " +"maintainers." msgstr "**做好功课,并告诉大家你已经做了功课**。如果使用开源软件时遇到问题,请先尽力自行解决。无法解决问题并不丢人,这反而有助于完善你的错误报告。在提交错误报告或通过项目沟通渠道寻求帮助时,务必注明你已采取的解决步骤。这样做能节省他人的时间和精力,因为维护者不会要求你重复已经尝试过的方案。列出你已尝试的自助方法,是对项目维护者时间与精力的尊重。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:306 msgid "" "**Practice [basic " -"netiquette](https://en.wikipedia.org/wiki/Etiquette_in_technology).** Most " -"fundamental advice for communicating on the internet is applicable in open " -"source projects and communities. For instance, avoid typing in all capital " -"letters, as this style is read as shouting (and one would not go about " -"asking for help by shouting at someone). Choose a username or screen name " -"that is reasonable and approachable, otherwise you risk not being taken " -"seriously by others. Wait a reasonable amount of time—say 24 to 48 hours—for" -" a response to your inquiry before trying to get a response in a different " -"communication channel. You may find Virgina Shea's oft-cited [The Core Rules" -" of Netiquette](http://www.albion.com/netiquette/corerules.html) to be a " +"netiquette](https://en.wikipedia.org/wiki/Etiquette_in_technology).** " +"Most fundamental advice for communicating on the internet is applicable " +"in open source projects and communities. For instance, avoid typing in " +"all capital letters, as this style is read as shouting (and one would not" +" go about asking for help by shouting at someone). Choose a username or " +"screen name that is reasonable and approachable, otherwise you risk not " +"being taken seriously by others. Wait a reasonable amount of time—say 24 " +"to 48 hours—for a response to your inquiry before trying to get a " +"response in a different communication channel. You may find Virgina " +"Shea's oft-cited [The Core Rules of " +"Netiquette](http://www.albion.com/netiquette/corerules.html) to be a " "useful resource if you are unfamiliar with the rules of engagement in " "internet communications." msgstr "" @@ -1388,30 +1411,32 @@ msgstr "" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:307 msgid "" "**Post questions and communications in the appropriate places.** " -"Encountering information in a place people don't expect can overwhelm them. " -"For example, using a project issue tracker to let folks know you are hosting" -" a hackfest next week is inappropriate. If the project has taken the time to" -" let contributors know how and where to ask questions—and you should know " -"this by following the guidance in the first item on this list—make sure to " -"use the appropriate forum to do so. Demonstrating you have taken the time " -"and energy to interact with the project's maintainers and other volunteers " -"in the way they've asked shows you respect their efforts and, in turn, makes" -" helping you be successful much easier for them." +"Encountering information in a place people don't expect can overwhelm " +"them. For example, using a project issue tracker to let folks know you " +"are hosting a hackfest next week is inappropriate. If the project has " +"taken the time to let contributors know how and where to ask " +"questions—and you should know this by following the guidance in the first" +" item on this list—make sure to use the appropriate forum to do so. " +"Demonstrating you have taken the time and energy to interact with the " +"project's maintainers and other volunteers in the way they've asked shows" +" you respect their efforts and, in turn, makes helping you be successful " +"much easier for them." msgstr "**在合适的地方发布问题和交流信息**。人们在不预期的地方遇到信息会感到困扰。例如,使用项目的问题跟踪器来通知大家下周要举办黑客松就不合适。如果项目已经花时间告知贡献者提问的方式和渠道——你应该通过遵循本清单第一条的指引了解这点——请务必使用恰当的论坛进行交流。这表明你投入了时间和精力,按照项目维护者和其他志愿者要求的方式与他们互动,体现出你尊重他们的付出,进而让他们更易于帮助你取得成功。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:308 msgid "" -"**Make the subject of your posts as meaningful as possible.** When writing " -"the subject line of an email or forum post, make your needs explicit. For " -"example, a subject line that says \"I think I found a bug\" is likely to be " -"acted upon more slowly than one that says \"external display not recognized " -"upon upgrading to version 2.2.\" The second subject tells the reader that " -"they will likely find more detail on how to diagnose the problem, and that " -"they are dealing with someone who understands the limited amount of time and" -" attention the reader has. The first subject does not differentiate the " -"sender's problem in any way, and makes it difficult for your communication " -"to be memorable to the reader. The more useful the subject of your post, the" -" more likely you are to receive a prompt reply." +"**Make the subject of your posts as meaningful as possible.** When " +"writing the subject line of an email or forum post, make your needs " +"explicit. For example, a subject line that says \"I think I found a bug\"" +" is likely to be acted upon more slowly than one that says \"external " +"display not recognized upon upgrading to version 2.2.\" The second " +"subject tells the reader that they will likely find more detail on how to" +" diagnose the problem, and that they are dealing with someone who " +"understands the limited amount of time and attention the reader has. The " +"first subject does not differentiate the sender's problem in any way, and" +" makes it difficult for your communication to be memorable to the reader." +" The more useful the subject of your post, the more likely you are to " +"receive a prompt reply." msgstr "" "**尽量让帖子标题富有意义**。在撰写邮件或论坛帖子的标题时,要明确表达需求。例如,标题为\"我想我发现了一个漏洞\"的帖子,其处理速度很可能比\"升级至" " 2.2 " @@ -1420,15 +1445,15 @@ msgstr "" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:309 msgid "" "**Be kind and courteous in all your communications.** Once more, let's " -"stress that the key to effective communication in any project—open source " -"software or otherwise—is thoughtful and gracious behavior. Do not show up at" -" an open source project angrily demanding help for your problems, send " -"impolite follow up messages when you do not get an immediate answer, or " -"otherwise be unkind to the people with whom you are communicating. Do take " -"the time to thank them for their help and for providing the project to you " -"and everyone else. Remember you are communicating with other people, some of" -" whom are spending their free time to write your free software. Treat them " -"with the respect and courtesy you want for yourself." +"stress that the key to effective communication in any project—open source" +" software or otherwise—is thoughtful and gracious behavior. Do not show " +"up at an open source project angrily demanding help for your problems, " +"send impolite follow up messages when you do not get an immediate answer," +" or otherwise be unkind to the people with whom you are communicating. Do" +" take the time to thank them for their help and for providing the project" +" to you and everyone else. Remember you are communicating with other " +"people, some of whom are spending their free time to write your free " +"software. Treat them with the respect and courtesy you want for yourself." msgstr "**在任何交流中都要保持友善与礼貌**。再次强调,无论开源软件还是其他项目,有效沟通的关键在于体贴和得体的行为。不要怒气冲冲地出现在开源项目中,强硬地要求解决你的问题;没有得到即时回复时,别发送不礼貌的催促信息;也不要对交流对象表现出任何不友善的态度。务必花时间感谢他们提供的帮助,以及为所有人贡献的这个项目。请记住,你是在和他人沟通,其中有些人正利用业余时间为你编写免费软件。以你希望获得的尊重与礼遇对待他们。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:311 @@ -1437,24 +1462,26 @@ msgstr "开源项目和学术界中沟通的发展" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:313 msgid "" -"While open source software now seems ubiquitous, we should recall that the " -"free and open source software movements are still in their early stages. " -"Development of the Linux operating system began in 1991. The Apache Software" -" Foundation, steward of many of the world's most notable open source " -"projects, was incorporated in 1999. Though 20 or 30 years seems like ancient" -" history on the internet, it is worth noting that Ada Lovelace created the " -"world's first algorithm back in the 1840s. Open source is still a blip " -"(albeit a significant one) in a much longer technological timeline." +"While open source software now seems ubiquitous, we should recall that " +"the free and open source software movements are still in their early " +"stages. Development of the Linux operating system began in 1991. The " +"Apache Software Foundation, steward of many of the world's most notable " +"open source projects, was incorporated in 1999. Though 20 or 30 years " +"seems like ancient history on the internet, it is worth noting that Ada " +"Lovelace created the world's first algorithm back in the 1840s. Open " +"source is still a blip (albeit a significant one) in a much longer " +"technological timeline." msgstr "" "尽管开源软件如今似乎无处不在,但我们应该记住,自由与开源软件运动仍处于早期阶段。Linux 操作系统的开发始于 1991 " -"年。管理着全球众多顶尖开源项目的 Apache 软件基金会则成立于 1999 年。虽然二三十年在互联网时代看似久远,但值得提及的是,埃达·洛夫莱斯早在 " -"19 世纪 40 年代就创造了世界上首个算法。在更漫长的技术发展历程中,开源仍是短暂却重要的一瞬。" +"年。管理着全球众多顶尖开源项目的 Apache 软件基金会则成立于 1999 " +"年。虽然二三十年在互联网时代看似久远,但值得提及的是,埃达·洛夫莱斯早在 19 世纪 40 " +"年代就创造了世界上首个算法。在更漫长的技术发展历程中,开源仍是短暂却重要的一瞬。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:315 msgid "" -"Due to open source's disruptive influence in the software industry, academic" -" researchers have found open source software projects and their development " -"methodologies particularly worthy of study." +"Due to open source's disruptive influence in the software industry, " +"academic researchers have found open source software projects and their " +"development methodologies particularly worthy of study." msgstr "由于开源对软件行业的颠覆性影响,学术研究者发现开源软件项目及其开发方法尤其值得研究。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:317 @@ -1463,10 +1490,10 @@ msgid "" "researchers' ability to access project data for the purpose of study has " "been, at times, diminished. For example, parsing IRC logs of a project's " "real-time chat often yielded fruitful information about a particular " -"project, but as some projects have moved to other chat systems, such logs " -"are no longer commonly available (nor has there been any guaranteed " -"longevity of the project's chat archives, depending on which communication " -"tool the project chooses)." +"project, but as some projects have moved to other chat systems, such logs" +" are no longer commonly available (nor has there been any guaranteed " +"longevity of the project's chat archives, depending on which " +"communication tool the project chooses)." msgstr "" "然而,随着项目沟通工具和平台的发展演变,研究人员为研究目的获取项目数据的能力有时会有所削弱。例如,解析项目中实时聊天的 IRC " "日志通常能获得关于特定项目的丰富信息,但随着一些项目迁移至其他聊天系统,这类日志已不再普遍可用(且根据项目选择的沟通工具不同,其聊天记录的保存期限也无法得到保证)。" @@ -1476,14 +1503,14 @@ msgid "" "When a project launches or consists of a small group of people working " "together, choices for how to communicate and where to do so often arise " "organically and with little consideration to the future impact of those " -"choices. But project maintainers should thoughtfully consider how they can " -"ensure the project's communications—which contain potentially rich sources " -"of data and historical artifacts like lore and decisions histories—are " -"effectively captured for both the project participants and interested " -"observers. To understand how researchers benchmark community activity and " -"analyse the outputs of various parts of your project, consider reviewing the" -" work of the [Community Health Analytics in Open Source " -"Software](https://chaoss.community/) (CHAOSS) Project." +"choices. But project maintainers should thoughtfully consider how they " +"can ensure the project's communications—which contain potentially rich " +"sources of data and historical artifacts like lore and decisions " +"histories—are effectively captured for both the project participants and " +"interested observers. To understand how researchers benchmark community " +"activity and analyse the outputs of various parts of your project, " +"consider reviewing the work of the [Community Health Analytics in Open " +"Source Software](https://chaoss.community/) (CHAOSS) Project." msgstr "当一个项目启动或由一小群人协作时,沟通方式和平台的选择往往自发形成,很少考虑这些选择未来的影响。但项目维护者应当深思熟虑,如何确保项目沟通内容——包含潜在丰富的数据源和历史记录(如项目传说和决策历史)——能被项目参与者和感兴趣的观察者有效获取。要了解研究者如何衡量社区活跃度并分析项目各环节产出,建议参考[开源软件社区健康分析](https://chaoss.community/)(CHAOSS)项目的研究成果。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:321 @@ -1492,14 +1519,14 @@ msgstr "结论" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:323 msgid "" -"The most effective way to achieve communication in open source projects is " -"to show others kindness and courtesy, and to assume good intent upon first " -"contact with people you've never met. Though this chapter contains any " -"number of helpful best practices for effective communication, simply acting " -"with graciousness to other people is the most important step one can take to" -" communicate well. Remember there is a human being reading what you have " -"written, and remember to treat them with the same respect you want for " -"yourself." +"The most effective way to achieve communication in open source projects " +"is to show others kindness and courtesy, and to assume good intent upon " +"first contact with people you've never met. Though this chapter contains " +"any number of helpful best practices for effective communication, simply " +"acting with graciousness to other people is the most important step one " +"can take to communicate well. Remember there is a human being reading " +"what you have written, and remember to treat them with the same respect " +"you want for yourself." msgstr "在开源项目中实现高效沟通的最佳方式是以善意和礼貌待人,初次接触素未谋面者时秉持善意揣测。尽管本章包含众多有效沟通的最佳实践指南,但以优雅姿态待人始终是达成良好沟通的首要前提。请牢记:屏幕另一端阅读你文字的是有血有肉的人,请以你期望获得的同等尊重相待。" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:325 @@ -1517,9 +1544,9 @@ msgstr "" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:327 msgid "" -"The authors are grateful for the work of Kent C.Dodds and Sara Drasner in " -"their article [An Open Source Etiquette Guidebook](https://css-tricks.com" -"/open-source-etiquette-guidebook/)." +"The authors are grateful for the work of Kent C.Dodds and Sara Drasner in" +" their article [An Open Source Etiquette Guidebook](https://css-" +"tricks.com/open-source-etiquette-guidebook/)." msgstr "" "作者感谢 Kent C.Dodds 和 Sara Drasner 在其文章 [《开源礼仪指南》](https://css-tricks.com" "/open-source-etiquette-guidebook/) 中所做的工作。" @@ -1527,7 +1554,8 @@ msgstr "" #: ../../attracting-users/communication-norms-in-open-source-software-projects.md:329 msgid "" "[https://producingoss.com/en/producingoss-" -"letter.pdf](https://producingoss.com/en/producingoss-letter.pdf), page 64." +"letter.pdf](https://producingoss.com/en/producingoss-letter.pdf), page " +"64." msgstr "" "[https://producingoss.com/en/producingoss-" "letter.pdf](https://producingoss.com/en/producingoss-letter.pdf),第 64 页。" diff --git a/locales/zh_CN/LC_MESSAGES/getting-started/new-project-checklist.po b/locales/zh_CN/LC_MESSAGES/getting-started/new-project-checklist.po index 37583ec..38edfce 100644 --- a/locales/zh_CN/LC_MESSAGES/getting-started/new-project-checklist.po +++ b/locales/zh_CN/LC_MESSAGES/getting-started/new-project-checklist.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: The Open Source Way \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 1970-01-01 00:00+0000\n" +"POT-Creation-Date: 1970-01-01 00:00+0800\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: zh_CN\n" @@ -26,18 +26,18 @@ msgstr "新项目启动清单" #: ../../getting-started/new-project-checklist.md:9 msgid "" -"This is a relatively simple checklist for you to consider when starting a " -"new open source project, especially where the project may be starting small " -"but wants room to grow. By \"simple\" we mean: This list doesn't propose a " -"process or project management for accomplishing these items. In its most " -"simple form it does not have definitions for items; it suggests what is to " -"come without prescribing or demanding obedience to the list." +"This is a relatively simple checklist for you to consider when starting a" +" new open source project, especially where the project may be starting " +"small but wants room to grow. By \"simple\" we mean: This list doesn't " +"propose a process or project management for accomplishing these items. In" +" its most simple form it does not have definitions for items; it suggests" +" what is to come without prescribing or demanding obedience to the list." msgstr "这是一份相对简单的清单,供你在启动新开源项目时参考,尤其适用于那些初期规模较小但希望留有发展空间的项目。所谓简单是指:本清单不涉及完成这些事项的具体流程或项目管理方法。最“简单”的形式下,它不包含各项的定义说明;仅提示可能涉及的方面,而非强制要求逐条遵守。" #: ../../getting-started/new-project-checklist.md:11 msgid "" -"These are separated out into several different lists, depending on the area " -"covered:" +"These are separated out into several different lists, depending on the " +"area covered:" msgstr "根据涵盖领域的不同,这些内容被划分为若干独立清单:" #: ../../getting-started/new-project-checklist.md:13 @@ -45,148 +45,148 @@ msgid "Goals of project" msgstr "项目目标" #: ../../getting-started/new-project-checklist.md:15 -msgid "[ ] Technical problem addressed by the project" -msgstr "[ ] 项目解决的技术难题" +msgid "Technical problem addressed by the project" +msgstr "项目解决的技术难题" #: ../../getting-started/new-project-checklist.md:16 -msgid "[ ] Intended users and value proposition" -msgstr "[ ] 目标用户与价值主张" +msgid "Intended users and value proposition" +msgstr "目标用户与价值主张" #: ../../getting-started/new-project-checklist.md:17 -msgid "[ ] Establish beginning roadmap with milestones" -msgstr "[ ] 制定初步路线图,包含关键里程碑" +msgid "Establish beginning roadmap with milestones" +msgstr "制定初步路线图,包含关键里程碑" #: ../../getting-started/new-project-checklist.md:19 msgid "Market positioning" msgstr "市场定位" #: ../../getting-started/new-project-checklist.md:21 -msgid "[ ] List of related/similar projects" -msgstr "[ ] 相关/类似项目清单" +msgid "List of related/similar projects" +msgstr "相关/类似项目清单" #: ../../getting-started/new-project-checklist.md:22 -msgid "[ ] Why a net-new project?" -msgstr "[ ] 为什么要启动全新项目?" +msgid "Why a net-new project?" +msgstr "为什么要启动全新项目?" #: ../../getting-started/new-project-checklist.md:23 -msgid "[ ] Key differentiators" -msgstr "[ ] 核心差异化优势" +msgid "Key differentiators" +msgstr "核心差异化优势" #: ../../getting-started/new-project-checklist.md:25 msgid "Project name" msgstr "项目名称" #: ../../getting-started/new-project-checklist.md:27 -msgid "[ ] Compile and vet candidate list" -msgstr "[ ] 汇总并筛选候选名单" +msgid "Compile and vet candidate list" +msgstr "汇总并筛选候选名单" #: ../../getting-started/new-project-checklist.md:28 -msgid "[ ] Logo design" -msgstr "[ ] 标识设计" +msgid "Logo design" +msgstr "标识设计" #: ../../getting-started/new-project-checklist.md:29 -msgid "[ ] Legal review (if required)" -msgstr "[ ] 法律审查(如需要)" +msgid "Legal review (if required)" +msgstr "法律审查(如需要)" #: ../../getting-started/new-project-checklist.md:30 -msgid "[ ] Reserve name (domain name, GitHub, social media handles, etc.)" -msgstr "[ ] 预留名称(域名、GitHub 账号、社交媒体账号等)" +msgid "Reserve name (domain name, GitHub, social media handles, etc.)" +msgstr "预留名称(域名、GitHub 账号、社交媒体账号等)" #: ../../getting-started/new-project-checklist.md:32 msgid "Licensing & legal" msgstr "许可与法律" #: ../../getting-started/new-project-checklist.md:34 -msgid "[ ] Document license criteria" -msgstr "[ ] 文档许可标准" +msgid "Document license criteria" +msgstr "文档许可标准" #: ../../getting-started/new-project-checklist.md:35 -msgid "[ ] License selection" -msgstr "[ ] 许可证选择" +msgid "License selection" +msgstr "许可证选择" #: ../../getting-started/new-project-checklist.md:36 -msgid "[ ] Need ™ or other mark registration?" -msgstr "[ ] 需要™或其他商标注册?" +msgid "Need ™ or other mark registration?" +msgstr "需要™或其他商标注册?" #: ../../getting-started/new-project-checklist.md:38 msgid "Governance" msgstr "治理机制" #: ../../getting-started/new-project-checklist.md:40 -msgid "[ ] Define officers & their responsibilities" -msgstr "[ ] 明确官员及其职责" +msgid "Define officers & their responsibilities" +msgstr "明确官员及其职责" #: ../../getting-started/new-project-checklist.md:41 -msgid "[ ] Org structure, voting requirements and process" -msgstr "[ ] 组织结构、投票要求与流程" +msgid "Org structure, voting requirements and process" +msgstr "组织结构、投票要求与流程" #: ../../getting-started/new-project-checklist.md:42 -msgid "[ ] Rules for amending governance" -msgstr "[ ] 治理章程修订规则" +msgid "Rules for amending governance" +msgstr "治理章程修订规则" #: ../../getting-started/new-project-checklist.md:43 -msgid "[ ] Rules for contribution, committer status" -msgstr "[ ] 贡献规则与提交者身份认定" +msgid "Rules for contribution, committer status" +msgstr "贡献规则与提交者身份认定" #: ../../getting-started/new-project-checklist.md:44 -msgid "[ ] Provisions for sub-projects and lifecycle management" -msgstr "[ ] 子项目与生命周期管理条款" +msgid "Provisions for sub-projects and lifecycle management" +msgstr "子项目与生命周期管理条款" #: ../../getting-started/new-project-checklist.md:45 -msgid "[ ] Privacy policy" -msgstr "[ ] 隐私政策" +msgid "Privacy policy" +msgstr "隐私政策" #: ../../getting-started/new-project-checklist.md:46 -msgid "[ ] Code of conduct" -msgstr "[ ] 行为准则" +msgid "Code of conduct" +msgstr "行为准则" #: ../../getting-started/new-project-checklist.md:47 -msgid "[ ] Foundation membership options, if planned" -msgstr "[ ] 基金会会员选项(如计划中)" +msgid "Foundation membership options, if planned" +msgstr "基金会会员选项(如计划中)" #: ../../getting-started/new-project-checklist.md:49 msgid "Project infrastructure" msgstr "项目基础设施" #: ../../getting-started/new-project-checklist.md:51 -msgid "[ ] Mail tool (and moderators)" -msgstr "[ ] 邮件工具(及版主)" +msgid "Mail tool (and moderators)" +msgstr "邮件工具(及版主)" #: ../../getting-started/new-project-checklist.md:52 -msgid "[ ] Forum/Chat (and moderators)" -msgstr "[ ] 论坛/聊天(及版主)" +msgid "Forum/Chat (and moderators)" +msgstr "论坛/聊天(及版主)" #: ../../getting-started/new-project-checklist.md:53 -msgid "[ ] Doc repository (slides, planning docs, etc.)" -msgstr "[ ] 文档库(幻灯片、规划文档等)" +msgid "Doc repository (slides, planning docs, etc.)" +msgstr "文档库(幻灯片、规划文档等)" #: ../../getting-started/new-project-checklist.md:54 -msgid "[ ] Web conferencing platform" -msgstr "[ ] 网络会议平台" +msgid "Web conferencing platform" +msgstr "网络会议平台" #: ../../getting-started/new-project-checklist.md:55 -msgid "[ ] Community calendar (tool + who will maintain)" -msgstr "[ ] 社区日历(工具及维护人员)" +msgid "Community calendar (tool + who will maintain)" +msgstr "社区日历(工具及维护人员)" #: ../../getting-started/new-project-checklist.md:56 -msgid "[ ] Public website and website maintenance" -msgstr "[ ] 公共网站及网站维护" +msgid "Public website and website maintenance" +msgstr "公共网站及网站维护" #: ../../getting-started/new-project-checklist.md:57 -msgid "[ ] CI/CD, development and test environments" -msgstr "[ ] 持续集成/持续交付(CI/CD)、开发与测试环境" +msgid "CI/CD, development and test environments" +msgstr "持续集成/持续交付(CI/CD)、开发与测试环境" #: ../../getting-started/new-project-checklist.md:58 -msgid "[ ] Lab requirements, how they will be acquired" -msgstr "[ ] 实验室需求及其获取方式" +msgid "Lab requirements, how they will be acquired" +msgstr "实验室需求及其获取方式" #: ../../getting-started/new-project-checklist.md:59 -msgid "[ ] Code contribution tools and process" -msgstr "[ ] 代码贡献工具与流程" +msgid "Code contribution tools and process" +msgstr "代码贡献工具与流程" #: ../../getting-started/new-project-checklist.md:60 -msgid "[ ] Project documentation platform" -msgstr "[ ] 项目文档平台" +msgid "Project documentation platform" +msgstr "项目文档平台" #: ../../getting-started/new-project-checklist.md:62 msgid "Ownership and financing" @@ -197,33 +197,33 @@ msgid "These items may be ignored if donating project assets to a foundation." msgstr "若将项目资产捐赠给基金会,以下事项可忽略。" #: ../../getting-started/new-project-checklist.md:66 -msgid "[ ] Website URL" -msgstr "[ ] 网站地址" +msgid "Website URL" +msgstr "网站地址" #: ../../getting-started/new-project-checklist.md:67 -msgid "[ ] Logo" -msgstr "[ ] 标识" +msgid "Logo" +msgstr "标识" #: ../../getting-started/new-project-checklist.md:68 -msgid "[ ] Social media handles" -msgstr "[ ] 社交媒体账号" +msgid "Social media handles" +msgstr "社交媒体账号" #: ../../getting-started/new-project-checklist.md:69 -msgid "[ ] Web conferencing platform (if paid)" -msgstr "[ ] 网络会议平台(如为付费服务)" +msgid "Web conferencing platform (if paid)" +msgstr "网络会议平台(如为付费服务)" #: ../../getting-started/new-project-checklist.md:70 -msgid "[ ] Process for funding project needs" -msgstr "[ ] 项目需求资金筹措流程" +msgid "Process for funding project needs" +msgstr "项目需求资金筹措流程" #: ../../getting-started/new-project-checklist.md:72 msgid "Launch planning" msgstr "发布规划" #: ../../getting-started/new-project-checklist.md:74 -msgid "[ ] D&I plan" -msgstr "[ ] 多元化与包容性计划" +msgid "D&I plan" +msgstr "多元化与包容性计划" #: ../../getting-started/new-project-checklist.md:75 -msgid "[ ] Community health and metrics vision/plan" -msgstr "[ ] 社区健康度与指标愿景/计划" +msgid "Community health and metrics vision/plan" +msgstr "社区健康度与指标愿景/计划" diff --git a/locales/zh_CN/LC_MESSAGES/growing-contributors/community-manager-self-care.po b/locales/zh_CN/LC_MESSAGES/growing-contributors/community-manager-self-care.po index 32041f8..15dfda0 100644 --- a/locales/zh_CN/LC_MESSAGES/growing-contributors/community-manager-self-care.po +++ b/locales/zh_CN/LC_MESSAGES/growing-contributors/community-manager-self-care.po @@ -24,20 +24,17 @@ msgstr "" msgid "Community Manager Self-Care" msgstr "社区管理者自我健康管理" -#: ../../growing-contributors/community-manager-self-care.md:9 +#: ../../growing-contributors/community-manager-self-care.md:10 #, python-brace-format, python-format msgid "" -"{% hint style=\"danger\" %} Materials in this chapter are for " -"informational purposes only, not for the purpose of providing medical " -"advice. This chapter is not intended as a substitute for professional " -"medical advice, diagnosis, or treatment. Always seek the advice of your " -"physician or other qualified health care provider with any questions or " -"concerns you may have regarding your health, both mental and physical. {%" -" endhint %}" +"Materials in this chapter are for informational purposes only, not for " +"the purpose of providing medical advice. This chapter is not intended as " +"a substitute for professional medical advice, diagnosis, or treatment. " +"Always seek the advice of your physician or other qualified health care " +"provider with any questions or concerns you may have regarding your " +"health, both mental and physical." msgstr "" -"{% hint style=\"danger\" %} " "本章材料仅供信息参考之用,并非旨在提供医疗建议。本章内容不能替代专业的医疗建议、诊断或治疗。对于你可能有的任何身心健康问题或疑虑,请务必咨询你的医生或其他合格的医疗服务提供者。" -" {% endhint %}" #: ../../growing-contributors/community-manager-self-care.md:13 msgid "" @@ -107,7 +104,6 @@ msgid "The WHO (World Health Organization) defines self-care as:" msgstr "世界卫生组织(WHO)将自我健康管理定义为:" #: ../../growing-contributors/community-manager-self-care.md:29 -#, fuzzy msgid "" "\"Self-care is the ability of individuals, families and communities to " "promote health, prevent disease, maintain health, and to cope with " @@ -146,7 +142,6 @@ msgid "Emotional contagion" msgstr "情绪传染" #: ../../growing-contributors/community-manager-self-care.md:39 -#, fuzzy msgid "" "Community managers are often seen as leaders, the people everyone can " "turn to, an inspiration for others to emulate. This seemingly high " @@ -174,7 +169,6 @@ msgid "" msgstr "踏上自我健康管理之路的首要任务之一,便是觉察自身情绪状态对社区可能产生的影响。" #: ../../growing-contributors/community-manager-self-care.md:45 -#, fuzzy msgid "" "Emotions (both positive and negative) are [highly contagious](#user-" "content-fn-3)[^3]. Our emotional expressions have the power to " @@ -258,7 +252,6 @@ msgid "" msgstr "但\"掌控局面\"、\"被控制\"和\"处于可控状态\"之间存在本质区别。" #: ../../growing-contributors/community-manager-self-care.md:65 -#, fuzzy msgid "" "The belief that \"being in control is a reflection of our confidence in " "what we produce\" is inaccurate. It actually demonstrates that we are " @@ -313,7 +306,6 @@ msgid "" msgstr "维持这种情感劳动可能令人崩溃。我们必须承认并接受:完美无法企及,更重要的是——这从来不是成为优秀领导者的必要条件。真正重要的是人们能感受到你作为普通人的一面。" #: ../../growing-contributors/community-manager-self-care.md:77 -#, fuzzy msgid "" "People gravitate to others with whom they [share a kinship](#user-" "content-fn-6)[^6], and being able to identify this feeling of kinship is " @@ -546,7 +538,6 @@ msgid "Burnout" msgstr "过劳" #: ../../growing-contributors/community-manager-self-care.md:145 -#, fuzzy msgid "" "What exactly is burnout? The [WHO definition of burnout](#user-content-" "fn-7)[^7] is:" @@ -559,7 +550,6 @@ msgid "" msgstr "\"职业过劳是一种因长期工作压力未能得到有效管理而产生的综合征。\"" #: ../../growing-contributors/community-manager-self-care.md:149 -#, fuzzy msgid "" "Burnout can affect us all and in any occupation, however it seems more " "prevalent in roles that are mentally and emotionally draining for " @@ -570,7 +560,6 @@ msgid "" msgstr "职业过劳可能影响我们每个人,无论身处何种行业。然而,在那些长期消耗心智与情感的岗位上,这种现象似乎更为普遍。究其原因,往往与这些岗位中盛行的无私精神有关——人们习惯于将他人置于首位[^8]:无论是为了客户还是社群,他们总是不遗余力地营造愉悦满足的环境或氛围。" #: ../../growing-contributors/community-manager-self-care.md:151 -#, fuzzy msgid "" "It is also appearing [more and more within the tech industry](#user-" "content-fn-9)[^9]. This increase has been attributed to the seemly " @@ -604,7 +593,6 @@ msgid "" msgstr "职业过劳极难被察觉,这不仅因其症状隐蔽且呈渐进性发展,更因它常被误诊为早期阶段更短暂、更常见的职场压力。二者症状相似,直到为时已晚,问题已演变成更严重、更难治愈的深层次病症。" #: ../../growing-contributors/community-manager-self-care.md:159 -#, fuzzy msgid "" "Psychologist Herbert Freudenberger has released multiple books and " "articles since the 1970s regarding his research of the possible causes, " @@ -628,7 +616,6 @@ msgid "Exhaustion" msgstr "崩溃" #: ../../growing-contributors/community-manager-self-care.md:165 -#, fuzzy msgid "" "Loss of energy and accompanying feelings of weariness are usually the " "first distress signals especially if you naturally [have high energy " @@ -750,7 +737,6 @@ msgid "Paranoia" msgstr "妄想症" #: ../../growing-contributors/community-manager-self-care.md:197 -#, fuzzy msgid "" "[Leading from the signs of feeling unappreciated to feeling as though the" " world is against us](#user-content-fn-12)[^12]. When things go wrong, " @@ -795,7 +781,6 @@ msgid "Burnout cycle" msgstr "过劳循环" #: ../../growing-contributors/community-manager-self-care.md:209 -#, fuzzy msgid "" "Freudenberger and his colleague Gail North [later categorized the " "consequences](#user-content-fn-13)[^13] of these symptoms into 12 phases " @@ -912,7 +897,6 @@ msgid "" msgstr "既然我们已经认识到过劳的破坏性影响,现在让我们探讨这些症状可能源自我们的工作角色,甚至来自社区内部。" #: ../../growing-contributors/community-manager-self-care.md:232 -#, fuzzy msgid "" "We earlier described that burnout is a combination of many factors but a " "recurring element is the realization, subconsciously or not, that we " @@ -1002,7 +986,6 @@ msgid "Work overload" msgstr "工作超负荷" #: ../../growing-contributors/community-manager-self-care.md:256 -#, fuzzy msgid "" "Probably the most common experience contributing to burnout is [the over-" "burdening of one’s workload](#user-content-fn-16)[^16], whether from our " @@ -1032,7 +1015,6 @@ msgid "Preventing/treating burnout" msgstr "预防/应对职业过劳" #: ../../growing-contributors/community-manager-self-care.md:264 -#, fuzzy msgid "" "If you feel yourself or anyone else succumbing to burnout then the most " "direct approach is to take a break from the source of the stress, which " @@ -1443,7 +1425,6 @@ msgid "Tackling imposter syndrome" msgstr "应对冒充者综合征" #: ../../growing-contributors/community-manager-self-care.md:360 -#, fuzzy msgid "" "This term was first defined by [psychologists Dr. Pauline Clance and Dr. " "Suzanne Imes](#user-content-fn-18)[^18] in the 1970s as the internal " @@ -1466,7 +1447,6 @@ msgid "" msgstr "冒充者综合征患者往往难以内化和接纳自身成就,他们习惯弱化积极反馈,并将他人工作与自身进行比较。当我们开始新工作、承担新职责或角色、或是结束职业空窗期重返岗位时,这种情况更易发生。为补偿这种长期自我怀疑,我们开始加班工作、拖延事务,或以不必要的方式试图证明自身价值的合理性。" #: ../../growing-contributors/community-manager-self-care.md:364 -#, fuzzy msgid "" "Dr. Valerie Young [further categorized these types of flawed thinking" "](#user-content-fn-19)[^19] of what sufferers believe it takes to be " @@ -1624,7 +1604,6 @@ msgid "" msgstr "我们深知社区的力量,它能将人们凝聚在一起。在正确的引导和满满的爱意之下,我们甚至可以移山填海。但为什么我们总觉得,对自己却无法抱持同样的心态呢?" #: ../../growing-contributors/community-manager-self-care.md:412 -#, fuzzy msgid "" "During stressful and tough times, whether it’s just a bad day, or more " "chronic episodes of illness, research has shown that having a " @@ -1637,7 +1616,6 @@ msgid "" msgstr "无论是遭遇糟糕的一天,还是长期与疾病抗争,研究表明:拥有一个紧密(未必庞大)的社会支持网络对身心健康至关重要[^20]。若缺乏这样的网络,孤独与隔绝感便会滋生,进而加剧抑郁和焦虑[^21]。往往正是这个支持网络——即便我们自以为孤立无援——最先察觉我们行为举止的异常,甚至早于我们自己的觉察。" #: ../../growing-contributors/community-manager-self-care.md:414 -#, fuzzy msgid "" "[A social support network is made up of friends, family, and peers" "](#user-content-fn-22)[^22]. Although this is different from a support " @@ -1667,7 +1645,6 @@ msgid "" msgstr "我们可能会发现,社区中的那些朝夕相处的伙伴,逐渐成为了我们社会支持网络的一部分。每个人都以独特的方式为我们提供支持,在生活中给予不同形式的帮助。但同样要记住,我们也应当成为他人支持网络中的一环。" #: ../../growing-contributors/community-manager-self-care.md:420 -#, fuzzy msgid "" "The more education and communicating with our members about the benefits " "of self-care, the more likely we will see it being practiced and " @@ -1682,7 +1659,6 @@ msgid "" msgstr "越是向成员普及自我健康管理的益处并加强沟通,就越能看到这种行为被实践和鼓励。这反过来有助于在社区中营造更加关怀与包容的氛围。教育可以采取多种形式:开展倡导自我健康管理的讨论、举办心理健康宣传活动[^23],在新成员加入[^25]时将相关条款加入社区指南[^24](如鼓励团队成员在工作量或其他因素影响健康时及时沟通),或组织心理健康意识培训。" #: ../../growing-contributors/community-manager-self-care.md:422 -#, fuzzy msgid "" "If you see a member on the team or community showing symptoms of burnout " "then reach out to them and let them know you are concerned for their well" @@ -1692,7 +1668,6 @@ msgid "" msgstr "如果你发现团队或社区中某位成员出现过劳症状,请主动联系并表达对其健康的关切。表明你随时准备提供支持,大多数情况下他们会积极回应,并共同协作缓解压力[^26]。" #: ../../growing-contributors/community-manager-self-care.md:424 -#, fuzzy msgid "" "However, it is important to make clear here that if we feel that we are " "unable to assist a community member’s emotional stress beyond our role’s " diff --git a/tools/convert_gitbook.py b/tools/convert_gitbook.py new file mode 100644 index 0000000..73c2437 --- /dev/null +++ b/tools/convert_gitbook.py @@ -0,0 +1,76 @@ +#!/usr/bin/env python3 +"""Convert GitBook-specific Markdown syntax to MyST equivalents. + +The guidebook source (a git submodule) still uses GitBook's +``{% hint style="..." %}...{% endhint %}`` callout syntax, which MyST/Sphinx +does not understand and renders as literal text. This script rewrites those +blocks into MyST admonition directives in the staging tree, leaving the +submodule untouched. + +Run it over the staging directory after the source has been copied in (see +``tools/prepare-source.sh``). +""" + +from __future__ import annotations + +import re +import sys +from pathlib import Path + +# GitBook hint style -> MyST admonition directive name. Sphinx ships localized +# titles for these directives, so translations keep working automatically. +_STYLE_TO_DIRECTIVE = { + "success": "tip", + "info": "note", + "warning": "warning", + "danger": "danger", +} + +_HINT_RE = re.compile( + r'{%\s*hint\s+style="(?P