mirror of
https://github.com/LCTT/TranslateProject.git
synced 2024-12-26 21:30:55 +08:00
翻已完成
This commit is contained in:
echoma
parent
3b70c35e8c
commit
aeac17a4ca
@ -1,103 +0,0 @@
|
||||
echoma 翻译中
|
||||
|
||||
Tips for managing your project's issue tracker
|
||||
==============================================
|
||||
|
||||
|
||||
|
||||
Issue-tracking systems are important for many open source projects, and there are many open source tools that provide this functionality but many projects opt to use GitHub's built-in issue tracker.
|
||||
|
||||
Its simple structure makes it easy for others to weigh in, but issues are really only as good as you make them.
|
||||
|
||||
Without a process, your repository can become unwieldy, overflowing with duplicate issues, vague feature requests, or confusing bug reports. Project maintainers can become burdened by the organizational load, and it can become difficult for new contributors to understand where priorities lie.
|
||||
|
||||
In this article, I'll discuss how to take your GitHub issues from good to great.
|
||||
|
||||
### The issue as user story
|
||||
|
||||
My team spoke with open source expert [Jono Bacon][1]—author of [The Art of Community][2], a strategy consultant, and former Director of Community at GitHub—who said that high-quality issues are at the core of helping a projects succeed. He says that while some see issues as merely a big list of problems you have to tend to, well-managed, triaged, and labeled issues can provide incredible insight into your code, your community, and where the problem spots are.
|
||||
|
||||
"At the point of submission of an issue, the user likely has little patience or interest in providing expansive detail. As such, you should make it as easy as possible to get the most useful information from them in the shortest time possible," Jono Bacon said.
|
||||
|
||||
A consistent structure can take a lot of burden off project maintainers, particularly for open source projects. We've found that encouraging a user story approach helps make clarity a constant. The common structure for a user story addresses the "who, what, and why" of a feature: As a [user type], I want to [task] so that [goal].
|
||||
|
||||
Here's what that looks like in practice:
|
||||
|
||||
>As a customer, I want to create an account so that I can make purchases.
|
||||
|
||||
We suggest sticking that user story in the issue's title. You can also set up [issue templates][3] to keep things consistent.
|
||||
|
||||
|
||||
> Issue templates bring consistency to feature requests.
|
||||
|
||||
The point is to make the issue well-defined for everyone involved: it identifies the audience (or user), the action (or task), and the outcome (or goal) as simply as possible. There's no need to obsess over this structure, though; as long as the what and why of a story are easy to spot, you're good.
|
||||
|
||||
### Qualities of a good issue
|
||||
|
||||
Not all issues are created equal—as any OSS contributor or maintainer can attest. A well-formed issue meets these qualities outlined in [The Agile Samurai][4].
|
||||
|
||||
Ask yourself if it is...
|
||||
|
||||
- something of value to customers
|
||||
- avoids jargon or mumbo jumbo; a non-expert should be able to understand it
|
||||
- "slices the cake," which means it goes end-to-end to deliver something of value
|
||||
- independent from other issues if possible; dependent issues reduce flexibility of scope
|
||||
- negotiable, meaning there are usually several ways to get to the stated goal
|
||||
- small and easily estimable in terms of time and resources required
|
||||
- measurable; you can test for results
|
||||
|
||||
### What about everything else? Working with constraints
|
||||
|
||||
If an issue is difficult to measure or doesn't seem feasible to complete within a short time period, you can still work with it. Some people call these "constraints."
|
||||
|
||||
For example, "the product needs to be fast" doesn't fit the story template, but it is non-negotiable. But how fast is fast? Vague requirements don't meet the criteria of a "good issue", but if you further define these concepts—for example, "the product needs to be fast" can be "each page needs to load within 0.5 seconds"—you can work with it more easily. Constraints can be seen as internal metrics of success, or a landmark to shoot for. Your team should test for them periodically.
|
||||
|
||||
### What's inside your issue?
|
||||
|
||||
In agile, user stories typically include acceptance criteria or requirements. In GitHub, I suggest using markdown checklists to outline any tasks that make up an issue. Issues should get more detail as they move up in priority.
|
||||
|
||||
Say you're creating an issue around a new homepage for a website. The sub-tasks for that task might look something like this.
|
||||
|
||||
|
||||
>Use markdown checklists to split a complicated issue into several parts.
|
||||
|
||||
If necessary, link to other issues to further define a task. (GitHub makes this really easy.)
|
||||
|
||||
Defining features as granularly as possible makes it easier to track progress, test for success, and ultimately ship valuable code more frequently.
|
||||
|
||||
Once you've gathered some data points in the form of issues, you can use APIs to glean deeper insight into the health of your project.
|
||||
|
||||
"The GitHub API can be hugely helpful here in identifying patterns and trends in your issues," Bacon said. "With some creative data science, you can identify problem spots in your code, active members of your community, and other useful insights."
|
||||
|
||||
Some issue management tools provide APIs that add additional context, like time estimates or historical progress.
|
||||
|
||||
### Getting others on board
|
||||
|
||||
Once your team decides on an issue structure, how do you get others to buy in? Think of your repo's ReadMe.md file as your project's "how-to." It should clearly define what your project does (ideally using searchable language) and explain how others can contribute (by submitting requests, bug reports, suggestions, or by contributing code itself.)
|
||||
|
||||
|
||||
>Edit your ReadMe file with clear instructions for new collaborators.
|
||||
|
||||
This is the perfect spot to share your GitHub issue guidelines. If you want feature requests to follow the user story format, share that here. If you use a tracking tool to organize your product backlog, share the badge so others can gain visibility.
|
||||
|
||||
"Issue templates, sensible labels, documentation for how to file issues, and ensuring your issues get triaged and responded to quickly are all important" for your open source project, Bacon said.
|
||||
|
||||
Remember: It's not about adding process for the process' sake. It's about setting up a structure that makes it easy for others to discover, understand, and feel confident contributing to your community.
|
||||
|
||||
"Focus your community growth efforts not just on growing the number of programmers, but also [on] people interested in helping issues be accurate, up to date, and a source of active conversation and productive problem solving," Bacon said.
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/life/16/7/how-take-your-projects-github-issues-good-great
|
||||
|
||||
作者：[Matt Butler][a]
|
||||
译者：[译者ID](https://github.com/译者ID)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创翻译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://opensource.com/users/mattzenhub
|
||||
[1]: http://www.jonobacon.org/
|
||||
[2]: http://www.artofcommunityonline.org/
|
||||
[3]: https://help.github.com/articles/creating-an-issue-template-for-your-repository/
|
||||
[4]: https://www.amazon.ca/Agile-Samurai-Masters-Deliver-Software/dp/1934356581
|
||||
@ -0,0 +1,101 @@
|
||||
几个小窍门帮你管理项目的问题追踪器
|
||||
==============================================
|
||||
|
||||
|
||||
|
||||
对于大多数开源项目来讲，问题追踪系统是至关重要的。虽然市面上有非常多的开源工具提供了这样的功能，但是大量项目还是选择了GitHub自带的问题追踪器（Issue Tracker）。
|
||||
|
||||
它结构简单，因此其他人可以非常轻松地参与进来，但这才刚刚开始。
|
||||
|
||||
如果没有适当的处理，你的代码仓库会挤满重复的问题单、模糊不明的特性需求单、混淆不清的bug报告单。项目维护者会被大量的组织内协调工作压得喘不过气来，新的贡献者也搞不清楚项目当前的重点工作是什么。
|
||||
|
||||
接下来，我们一起研究下，如何玩转GitHub的问题单。
|
||||
|
||||
### 问题单就是用户的故事
|
||||
|
||||
我的团队曾经和开源专家[Jono Bacon][1]做过一次对话，他是[The Art of Community][2]的作者、GitHub的战略顾问和前社区总监。他告诉我们，高质量的问题单是项目成功的关键。尽管有些人把问题单仅仅看作是一堆难题的列表，但是他认为这个难题列表是我们必须要时刻关注、完善管理并进行分类的。他还认为，给问题单打上标签的做法，会令人意想不到的提升我们对代码和社区的了解程度，也让我们更清楚问题的关键点在哪里。
|
||||
|
||||
“在提交问题单时，用户不太会有耐心或者有兴趣把问题的细节描述清楚。在这种情况下，你应当努力花最短的时间，尽量多的获取有用的信息。”，Jono Bacon说。
|
||||
|
||||
统一的问题单模板可以大大减轻项目维护者的负担，尤其是开源项目的维护者。我们发现，让用户讲故事的方法总是可以把问题描述的非常清楚。用户讲故事时需要说明“是谁，做了什么，为什么而做”，也就是：我是【何种用户】，为了【达到何种目的】，我要【做何种操作】。
|
||||
|
||||
实际操作起来，大概是这样的：
|
||||
|
||||
>我是一名顾客，我想付钱，所以我想创建个账户。
|
||||
|
||||
我们建议，问题单的标题始终使用这样的用户故事形式。你可以设置[问题单模板][3]来保证这点。
|
||||
|
||||
|
||||
> 问题单模板让特性需求单保持统一的形式
|
||||
|
||||
这个做法的核心点在于，问题单要被清晰的呈现给它涉及的每一个人：它要尽量简单的指明受众（或者说用户），操作（或者说任务），和收益（或者说目标）。你不需要拘泥于这个具体的模板，只要能把故事里的是什么事情或者是什么原因搞清楚，就达到目的了。
|
||||
|
||||
### 高质量的问题单
|
||||
|
||||
问题单的质量是参差不齐的，这一点任何一个开源软件的贡献者或维护者都能证实。具有良好格式的问题单所应具备的素质在[The Agile Samurai][4]有过概述。
|
||||
|
||||
问题单需要满足如下条件：
|
||||
|
||||
- 客户价值所在
|
||||
- 避免使用术语或晦涩的文字，就算不是专家也能看懂
|
||||
- 可以切分，也就是说我们可以一小步一小步的对最终价值进行交付
|
||||
- 尽量跟其他问题单没有瓜葛，这会降低我们在问题范围上的灵活性
|
||||
- 可以协商，也就说我们有好几种办法达到目标
|
||||
- 问题足够小，可以非常容易的评估出所需时间和资源
|
||||
- 可衡量，我们可以对结果进行测试
|
||||
|
||||
### 那其他的呢? 要有约束
|
||||
|
||||
如果一个问题单很难衡量，或者很难在短时间内完成，你也一样有办法搞定它。有些人把这种办法叫做”约束“。
|
||||
|
||||
例如，”这个软件要快“，这种问题单是不符合我们的故事模板的，而且是没办法协商的。多快才是快呢？这种模糊的需求没有达到”好问题单“的标准，但是如果你把一些概念进一步定义一下，例如”每个页面都需要在0.5秒内加载完“，那我们就能更轻松的解决它了。我们可以把”约束“看作是成功的标尺，或者是里程碑。每个团队都应该定期的对”约束“进行测试。
|
||||
|
||||
### 问题单里面有什么？
|
||||
|
||||
敏捷方法中，用户的故事里通常要包含验收指标或者标准。如果是在GitHub里，建议大家使用markdown的清单来概述完成这个问题单需要完成的任务。优先级越高的问题单应当包含更多的细节。
|
||||
|
||||
比如说，你打算提交一个问题单，关于网站的新版主页的。那这个问题单的子任务列表可能就是这样的：
|
||||
|
||||
|
||||
>使用markdown的清单把复杂问题拆分成多个部分
|
||||
|
||||
在必要的情况下，你还可以链接到其他问题单，那些问题单每个都是一个要完成的任务。（GitHub里做这个挺方便的）
|
||||
|
||||
将特性进行细粒度的拆分，这样更轻松的跟踪整体的进度和测试，要能更高频的发布有价值的代码。
|
||||
|
||||
一旦以问题单的形式收到数据，我们还可以用API更深入的了解软件的健康度。
|
||||
|
||||
”在统计问题单的类型和趋势时，GitHub的API可以发挥巨大作用“，Bacon告诉我们，”如果再做些数据挖掘工作，你就能发现代码里的问题点，谁是社区的活跃成员，或者其他有用的信息。“
|
||||
|
||||
有些问题单管理工具提供了API，通过API可以增加额外的信息，比如预估时间或者历史进度。
|
||||
|
||||
### 让大伙都上车
|
||||
|
||||
一旦你的团队决定使用某种问题单模板，你要想办法让所有人都按照模板来。代码仓库里的ReadMe.md其实也可以是项目的”How-to“文档。这个文档会描述清除这个项目是做什么的（最好是用可以搜索的语言），并且解释其他贡献者应当如何参与进来（比如提交需求单、bug报告、建议，或者直接贡献代码）
|
||||
|
||||
|
||||
>为新来的合作者在ReadMe文件里增加清晰的说明
|
||||
|
||||
ReadMe文件是提供”问题单指引“的完美场所。如果你希望特性需求单遵循”用户讲故事“的格式，那就把格式写在ReadMe里。如果你使用某种跟踪工具来管理待办事项，那就标记在ReadMe里，这样别人也能看到。
|
||||
|
||||
”问题单模板，合理的标签，如何提交问题单的文档，确保问题单被分类，所有的问题单都及时做出回复，这些对于开源项目都至关重要“，Bacon说。
|
||||
|
||||
记住一点：这不是为了完成工作而做的工作。这时让其他人更轻松的发现、了解、融入你的社区而设立的规则。
|
||||
|
||||
"关注社区的成长，不仅要关注参与开发者的的数量增长，也要关注那些在问题单上帮助我们的人，他们让问题单更加明确、保持更新，这是活跃沟通和高效解决问题的力量源泉"，Bacon说。
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/life/16/7/how-take-your-projects-github-issues-good-great
|
||||
|
||||
作者：[Matt Butler][a]
|
||||
译者：[echoma](https://github.com/echoma)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创翻译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://opensource.com/users/mattzenhub
|
||||
[1]: http://www.jonobacon.org/
|
||||
[2]: http://www.artofcommunityonline.org/
|
||||
[3]: https://help.github.com/articles/creating-an-issue-template-for-your-repository/
|
||||
[4]: https://www.amazon.ca/Agile-Samurai-Masters-Deliver-Software/dp/1934356581
|
||||
Loading…
Reference in New Issue
Block a user