contributing

KO | EN

gitlite — search

#python #hacktoberfest #llm #golang #android #rust #linux #docker #nodejs #windows #awesome #cli #mcp #open-source

(★ 91)

:clipboard: Guidelines & Workflow for people contributing to our project(s) on GitHub. Please :star: to confirm you've read & understood! :white_check_mark:

파일 탐색기

최종 버전 다운로드 (.zip)

CONTRIBUTING.md
notes-on-code-reviews-and-quality-assurance.md
README.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![welcome-teal](https://cloud.githubusercontent.com/assets/194400/22215755/76cb4dbc-e194-11e6-95ed-7def95e68f14.png)

Firstly, a ***heartfelt thank you*** for
making time to contribute to this project!

> As a **_distributed_ team**, 
we **_need_** a **contributing guide**
with **simple steps** people can **_easily_ follow** 
**so that** we _avoid confusion_ and
**keep our _communication consistently crystal clear_**!

Our contribution steps in a _nutshell_:
<!-- The text under the magnifying glass says: 
 "validate the need exists"
 "or undesired behavior"
 "from the user's perspective"

I believe this should be something like
        "validate the need or"
        "undesired behavior exists"
        "from the user's perspective"
      but the image is not in the repo
      so I can't modify it myself.
-->
![validate-idea](https://cloud.githubusercontent.com/assets/194400/22287688/a929a9ae-e2eb-11e6-8d16-f2ebbebea080.png "DWYL's Contribution Guidelines Steps Diagram")

***Please*** ***inform us*** if ***anything*** is ***unclear***
or if you have _**a suggestion** for how to **simplify/streamline**_ it!
[![Get Help!](https://img.shields.io/badge/get-help-brightgreen.svg?style=flat)](https://github.com/dwyl/contributing/issues)

# Contents Guide

+ **[Part 1](https://github.com/dwyl/contributing#part-1-describe-your-question-the-idea-or-user-story-in-an-issue):
  _Describe_ your Question, the Idea or User Story in an Issue**
  + [Step 1 Check if the issue already exists](https://github.com/dwyl/contributing#step-1-check-if-the-questionideastoryissue-already-exists-using-github-search-)
  + [Step 2: Create a new user story or report an issue](https://github.com/dwyl/contributing#step-2-create-a-new-user-story-or-report-an-issue-)
  + [Step 3: Submit the new issue and wait for validation](https://github.com/dwyl/contributing#step-3-submit-the-new-issue)
+ [What do I do next?](https://github.com/dwyl/contributing#what-do-i-do-next)
+ **[Part 2](https://github.com/dwyl/contributing#part-2-validate-the-need-user-story-or-issue-exists): Validate the Need (User Story) or Issue Exists**
  + [Step 1: Confirm the need](https://github.com/dwyl/contributing#step-1-confirm-the-need-in-the-new-storyissue)
  + [Step 2: Assign a priority to the issue](https://github.com/dwyl/contributing#step-2-assign-a-priority-to-the-storyissue)
+ **[Part 3](https://github.com/dwyl/contributing#part-3-do-the-work): Do the Work!**
  + [Step 1: Estimate the time required](https://github.com/dwyl/contributing#step-1-estimate-the-time-required-to-perform-the-work)
  + [Step 2: Assign yourself the issue](https://github.com/dwyl/contributing#step-2-assign-yourself-the-task-and-do-it)
  + [Step 3: Open the Pull Request (PR) and assign it for review](https://github.com/dwyl/contributing#step-3-prepare-a-pull-request-pr-and-assign-to-someone-else-for-review)
  + [Step 4: Reviewers review and merge PR](https://github.com/dwyl/contributing#step-4-reviewers-review-comment-on-and-merge-the-pull-request)
+ [Example User-focused "Story" Descriptions](https://github.com/dwyl/contributing#notes-on-effective-contributing)
  + [Example User-focused "Story" Descriptions](https://github.com/dwyl/contributing#example-user-focused-story-descriptions)
  + [Writing Good Issues](https://github.com/dwyl/contributing#include-anyall-relevant-information-in-the-issue-description)
+ [Practical Note on Time Estimation for a Story/Task](#practical-note-on-time-estimation-for-a-storytask)
  + [Revising a Time Estimate](https://github.com/dwyl/contributing#revising-a-time-estimate)
  + [Estimating for _open source_ projects without sprints](https://github.com/dwyl/contributing#estimating-for-open-source-modules-without-sprints)
+ [Notes on Creating Good Pull Requests](https://github.com/dwyl/contributing#notes-on-creating-good-pull-requests)
  + [1. Keep it Small and Simple](#1-keep-it-small-and-simple)
  + [2. Descriptive Pull Request Title and Description](#2-descriptive-pull-request-title-and-description)
  + [3. PR Etiquette](https://github.com/dwyl/contributing#3-pr-etiquette)
+ [Creating a New Repository](#creating-a-new-repository)
  + [Use Cases for Creating a New Repo](#use-cases-for-creating-a-new-repo)
  + [How?](#how)
  + [Minimum Requirements for a New Repository](#minimum-requirements-for-a-new-repository)
+ [Forking Repositories](#forking-repositories-into-dwyl)
+ [General Notes](https://github.com/dwyl/contributing#general-notes)

# Part 1: _Describe_ your Question, the Idea or User Story in an Issue

### _Why_ Use GitHub Issues...?

_Everything_ starts with a _thought_.
We collect _all_ our _thoughts_ in GitHub "issues". 
The issue can then be _**discussed, validated**
and **worked on** as a **team**_ while keeping ***everyone informed***. 
We use _issues_ to _log_ our user stories, sub/technical tasks
and any ***progress*** towards solving the issue, 
this ***ensures*** we have a
[_**single source** of **truth**_](https://github.com/dwyl/github-reference#why)
that _everyone_ can easily see!

### Step 1: Check if the Question/Idea/Story/Issue _Already Exists_ Using GitHub Search ![search](https://cloud.githubusercontent.com/assets/194400/22224334/255930a8-e1b6-11e6-9953-12cd4739aa1c.png)

1. Please take a moment to ***read through the existing stories/issues***
for the project 
to familiarize yourself with the _current_ "***backlog***".
(_There is a chance what you are thinking has **already** been **described**
 by someone else..._)

1. Try ***searching*** through the ***existing issues***
for _keywords_ associated with the story/issue you want to create. 
For example, you could use
https://github.com/dwyl/time/issues?utf8=%E2%9C%93&q=is%3Aissue%20app+icon
if `"app"` and `"icon"` were the keywords for what you have in mind
and you were searching in the "**Time**" project. 
![issue-matching-keyword-search](https://cloud.githubusercontent.com/assets/194400/22225715/852d9f78-e1bb-11e6-9d20-37492da92dc1.png)

1. If you ***find*** an _existing_ issue that matches what you were looking for,
_please_ click on the title of the issue, ***read the description*** to
confirm that it's what you are looking for, then ***comment*** on it
so we know more than one person has the need/issue. 
> _**Note**: If there is **already an issue** for what you were thinking,
you can **skip** steps 2 & 3.
as there's **no need** to create a **duplicate new issue**_.
![issue-search-for-app-icon](https://cloud.githubusercontent.com/assets/24758860/22225508/993c7ecc-e1ba-11e6-8a53-e8d2ac398546.png)

1. _Otherwise_, once you are _reasonably_ sure there is
no _existing_ question/issue/story covering what you have in mind,
_please_ **create** a ***new issue*** (_see next step_!)

### Step 2: Create a New User Story _or_ Report an Issue ![New Issue](https://cloud.githubusercontent.com/assets/194400/22224203/bbc5efb4-e1b5-11e6-9fcb-3aae75ae74ed.png)

1. Using the `New Issue` button, create an **issue**
  for the ***user story***
  (_feature request, expected or **unexpected** behaviour, or question_)
  you have in mind.

> _**Note**: If you are **new** to writing "**User Stories**",
please checkout out our **Example User-focused Story Descriptions**
section in the "Notes" section below_!

### Step 3: Submit the _New Issue_!

1. Submit the new issue!

2. Once you _submit_ a new issue for a User Story or Question/Issue/Bug, a member
of the team (_typically the Product Owner_) will ***review*** the issue.

3. That's _it_ from the side of the _issue_ creator! (_Thank you!_)

![thank-you-green-large](https://cloud.githubusercontent.com/assets/194400/22229077/5b0695ee-e1cd-11e6-9001-e5ff53afce36.jpg)

# _What do I do Next_...?

Once a new issue has been _created_,
it ***must*** be "***validated***"
by a ***different*** _member_ of the team/organisation.
(_see: "Part 2" below..._)

## :star: Star the Project! :star: (_share the love!_)

If you've found the project interesting, helpful or useful in _any way_,
_please_ ***star*** the repository on GitHub! 
Stars show _other_ members in the developer community
that it's a _**worthwhile project** or **learning resource**_
and one that can offer value to other developers like you! 🌟

# Questions?

### _Why_ Does the Issue _Need_ to be _Validated_? >> One Word: _Communication_

This _may initially feel_ a bit "_bureaucratic_" but
we _urge_ you _not_ to think of it as 
["_jumping through hoops_"](https://en.wiktionary.org/wiki/jump_through_hoops).
_We_ think of ***issue validation*** as something that:

+ ***ensures*** that **everyone** on the project
is ***aware*** of the issue/idea/story.

+ ***saves you time*** by ***avoiding*** ***duplicating effort***!
> The **Product Owner** (**PO**) or **Project Lead** (**PL**)
has _detailed knowledge_ of the _current_ issue backlog
and all _previous_ ("closed") issues. 
They know _how_ features/functionality _should_ work and can
validate things from the _user's_ perspective. 
***Most importantly*** the PO/PL ***knows*** if someone ***else***
is ***already*** working on the issue... 
And, _sometimes_ the _exact_ same issue has been "***solved before***"
in a _different_ project, so ***hours/days*** of effort can be saved!!

+ ***someone else*** might have **insight** they can share on the issue! 
> For example, if you have a **question** or are stuck on a challenge/problem,
[_**share** your **thoughts** and/or **progress**
towards "**solving**" it in **issue comments**_](https://github.com/dwyl/learn-nightwatch/issues/8#issuecomment-264734792)
you _never_ know when you will get _insight_ from a ***complete stranger***!

+ ***capturing information in issues*** _maintains_ ***relevance and focus***.
> The discussion is not "***lost***"
the way it would be in "_chat_"
and discussion are grouped by relevant topic.

+ ***clearly document*** the project so anyone _joining_ the team
_later_ on can see the "_history_".
> We have found this to be _invaluable_ when people are _learning_
why and how something works the way it does!

### How _Long_ Does it take for an Issue to be _Validated_?

We ***aim*** to respond to new issues within _**minutes**_
but during busy work days this can take up to ***a few hours***... 
(_**Thank you** for your **patience**!
 **Please** help us by giving as much useful information
 as possible in the issue description._)

### What can I do `while` I _wait_ for a my issue to be _validated_?
![what-to-do-while-waiting](https://cloud.githubusercontent.com/assets/194400/22229403/5a08474e-e1cf-11e6-8c1f-858f3a167315.jpg)

+ If you are ***itching*** to help "move the issue/story along"
you can help by _describing_ how the story/issue _could_
be implemented or "_fixed_" ... feel free to ***describe your thoughts***
in a **_follow-up_ comment** on the issue you _just_ created!

+ **_Please_ do not write _any_ code _until_**
the story/issue/bug has been ***verified***
(_by the product owner or project lead_). 
(_It's not that we "doubt" anyone's abilities or the validity of ideas/issues
we simply don't want people "wasting time" or "duplicating effort"
on un-verified issues...
also there are **many** other ways you can help `while` you wait..._)

> To help us **a lot**: go on a treasure hunt for an issue 
that _someone else_ created which has not had any comments ... 
or has not been _assigned_ to someone for investigation/work. 
this is quite easy to find by searching for a **label**:
[`help wanted`](https://github.com/search?q=org%3Adwyl+is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)

### Who can/should I assign my PR to?
Either **_the Project/Team Lead or "QA"_** (where applicable)
or in the case of an _open source module_, our "rule-of-thumb" is: look at the list of contributors
and assign your PR to **_the person who has made the most contributions_**.
If you are unable to assign your PR, simply mention the person by their username (**@** them!) in your PR description to notify them that your PR is "ready for review".

### Is it a "_Bug_"?

We also use GitHub issues to report "***unexpected behaviour***"
(_sometimes referred to as a "**bug**"_) in an app or module.
However, we use the word "**issue**" to ***generically***
mean ***any*** thought/thing we want to ***record*** in the project
and share with the team.
We ***reserve*** the word "**bug**" for a reported issue that
has been ***verified*** as **not functioning** according to the
***expected behaviour*** in the ***user acceptance test*** described
in the ***original user story***.

> Please do _not_ use the word "**bug**" or apply the `bug` label
until the issue has been ***validated***.

# Part 2: _Validate_ the Need (User Story) or Issue _Exists_

> A _different_ team member from the person who _created_ the issue
***must validate*** the User Story/Issue.

### Step 1: _Confirm_ the Need in the New Story/Issue

1. When a new issue (_user story, feature request or potential bug_)
is submitted by someone, we _require_ a _different_ person to verify it. 
_Typically_ this verification of need
is done by the "_Product Owner_" ("**PO**")
or the "_Project Leader_" ("**PL**"),
but in the case that the issue was _created_ by the PO/PL then a _different_
member of the team will need to _confirm_ their _understanding_ of the issue.

1. The person acknowledging the user story will add some **labels** to
the issue to help ***categorise*** it. eg. `question`, `discuss`, etc.

1. (_More_) Labels can always be added/removed at any time. The purpose of
labels is to help the team categorize and prioritize issues in the backlog see:
[complete list of labels](https://github.com/dwyl/labels/labels)

### Step 2: _Assign_ a _Priority_ to the Story/Issue

1. ***Always ensure*** that the Story/Issue focuses on ***only one thing***.
As soon as you see the word "***and***" in a story/issue, you know it is
trying to do more than one thing.
+ ***If*** the Story/Issue has **too many components or features***,
  split the user story into "***sub-stories***"
  (_often referred to as "**sub-tasks**"_)
  which you **link** to from the "main" story/issue.
  `-> Example of a Larger Story ("Epic") with Linked Sub-stories Required!`
  see: https://github.com/dwyl/contributing/issues/55
+ Product owner (or Project Maintainer) will add a
  priority label e.g: `Priority-2` to the story/issue.
+ Any/all Sub-Stories should _also_ be prioritized so that the team
can determine the _order_ in which they need to be worked on.

# Part 3: _Do_ the _Work_!

![get-it-done](https://cloud.githubusercontent.com/assets/194400/22265743/44a2ca72-e275-11e6-819d-2c5a1958ea11.png)

Once _all_ the previous steps have been performed
(_story/issue created, categorized with labels, any sub-stories/tasks
  created_)
and you are _sure_ you ***understand*** what is ***required***
(_make sure there are clear Acceptance Criteria_), add a comment on how you
propose to resolve/implement your resolution to the issue and
go for it!

### Step 1: _Estimate_ the Time Required to Perform the Work

1. For an _ongoing_ project, we estimate stories
 During "_Sprint Planning_" session; 
 A ***time estimate label*** (_e.g_: `T4h` or `T25m`) is added
 to each story (_and any Sub-Stories/tasks_) 
 The time estimate **_must_ factor** time to:
 + ***document*** the changes made to the codebase or UI
 + ***test*** both the code (_unit/functional tests_) and UI tests
 + ***develop*** the feature (_or fix the "bug"_)
 + ***deliver*** by submitting a PR and going through a review/QA cycle.
 + ***deploy*** the work to an environment
 where a non-technical peopler can _evaluate_ it against the original
 story description and acceptance criteria!

+ Wherever possible/practical/relevant **include** the person who
  **_originally_ created the story/issue** in the time estimation discussion.

+ For work in sprints, a **milestone** is added **at the sprint planning
session** to group the user stories with its relevant sprint;
this gives _everyone_ in the team a **_clear_ picture** of what is ***planned***.

> _Please **See below** for "**Practical Notes on Time Estimation**"_.

### Step 2: _Assign_ Yourself the Task and [_Do it_](https://youtu.be/M9-IZ1pNk00?t=45s)!

1. ***Assign*** the story/issue to yourself _before_ you start working.

2. ***Apply*** the `in-progress` **label** to the story/issue/sub-task so
  that your team knows when the work was started
  and that it is ***currently*** being worked.

3. ***Update*** the `README.md` ***before*** working on the task:
 _Ensuring_ you answer the questions: ***Why? What? How?***
 > This is referred to as
 ["***Readme Driven Development***"](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html)
 i.e: you ***document*** your work
 ***before*** you write ***any code***. 
 (_If this feels "tedious" to you, 
 remind yourself of the last time you
 "**inherited**" **undocumented code**..._) 
 **Watch**: ["**_The Mess_ We're In**" by Joe Armstrong](https://youtu.be/lKXe3HUG2l4?t=8m56s)

4. ***Log*** progress as
  [_comments in the issue_](https://github.com/dwyl/learn-nightwatch/issues/8)
  you are working on to keep everyone informed along
  the way. (**_This allows people to help you more effectively and gives
    your team/client/stakeholders something measurable_**).
  + If you _haven't finished_ your current task by the end of the day,
  take **5 minutes** to **_describe_ the progress** you've made
  and what else (_still_) needs to be done. _Anyone_ should be able
  to pick up and complete a user story by reading this description.
  + If you are leaving for more than a day,
  ***remove*** the `in-progress` **label**
  and ***un-assign yourself*** form the story.

5. ***Reference*** the **user story/issue/sub-task** you are working on
  by pasting a link to the GitHub issue
  in the **commit message**.

6. Once you have _committed_ your work/progress, push up your changes
 and then open a Pull Request _(even if the work isn't yet finished)_ 
 so that the rest of your team can easily see what you've been working on.
 (_Remember ..._)
 + Add `[WiP]` before the title of your PR and add that it's
 **NOT READY FOR REVIEW** in the description if it's still in progress.

### Step 3: _Prepare_ a Pull Request (PR) and _Assign_ (_to someone else_) for Review

> **Rule (of thumb)**: _**Keep Pull Requests Small and Focused**_.

1. ***Describe*** what your PR contains in the PR description;
it only takes a _few seconds_
but ***dramatically improves*** the ***review process***. 
(_Please **never** leave the PR description blank!
 remember this is in an exercise in **communicating with your team members**_!)

+ Make sure ***all tests*** are **passing**
 and (_where applicable_) that your **code coverage** is ***100%***.
 + ***Never*** _comment_ out a test that is failing.
 (_Don't laugh, we have seen "**cowboy developers**" do this...!
 If a test is failing, the feature is broken!
 Fix the feature to make the test pass. Only then is your work "**done**"_)
 + ***Never*** _assign_ a PR for "_review_"
 _until_ _**all CI checks** have **passed**_.
 ![check failed](https://cloud.githubusercontent.com/assets/194400/22284176/db2d698a-e2dd-11e6-8799-573226328b6b.png) 
 if _anything_ is failing on a PR and you _need_ help simply
 ***comment*** in the PR "_thread_" _asking_ for help!

+ Make sure your PR **adds to the `README`** to explain the latest changes made
(or explain specifically **why** you _haven't_ had to update the `README`).

+  **Increment** the _version_ of your application if it is a "_new release_".

+ ***Remove*** the `[WiP]` from your PR title.

+ **Remove** the `in-progress` label from the PR and associated issues.

+ ***Apply*** the
[`awaiting-review` **label**](https://github.com/dwyl/labels/issues/49) to the PR.

+ ***Assign*** someone `else` to _review_ your PR. 
(_Please don't merge your own PRs. We need to ensure every change
has been reviewed by at least one other person on the team. Thanks!_)

### Step 4: _Reviewer(s): Review_, _Comment On_ and _Merge_ the Pull Request

Always remember: a **Pull Requests** is a
"_**discussion thread** for **understanding** the code_".
Our objective is to _ensure_ the code works, is well documented/tested
and is "_free from errors_". We don't
["_nit pick_"](https://en.oxforddictionaries.com/definition/nitpicking)
if it's going to delay shipping. Equally, where code requires _clarification_,
tell people. ***Everyone*** benefits from _easy-to-read_ (easy-to-understand) code.

The person who is _assigned_ to review the PR
(_often referred to as the **Quality Assurance Person** or "**QA**"_) will:

1. ***Apply*** the
[`in-review` **label**](https://github.com/dwyl/labels/issues/48)
to the Pull Request to signal to other members of the team that the PR
is being reviewed. (_At this point, new commits which change large portions
  of the code being reviewed should not be pushed unless
  they are for changes that have been requested by the reviewer_)

1. ***Checkout*** the PR's _branch_ and run it on your local machine
following the instructions in the `README.md` file, where applicable.
> ***Confirm*** the tests pass and the app runs on your local machine.

1. ***Open the Issue(s)*** referenced in the Pull Request
and re-acquaint yourself with the User Stories so you can
***confirm*** the content of the PR **satisfies** the ***Acceptance Criteria***.

1. ***Review*** the _content_ (_documentation, tests, or code_)
in the Pull Request on GitHub...

1. ***Write comments*** or notes to the developer(s)
giving feedback on their code.
> See: "notes on code reviews": https://github.com/dwyl/contributing/issues/32#issuecomment-271089111 [![Get Help!](https://img.shields.io/badge/help-wanted-brightgreen.svg?style=flat)](https://github.com/dwyl/contributing/issues)

+ ***If***, for _any reason_, you are ***unsatisfied*** with the _content_ of the
pull request (_documentation, tests or code_), ***request changes***.
 + ***Don't be afraid*** to "_push back_" on a PR if the code is unclear,
***especially*** if the developer who's code you are reviewing is
"_more experienced_", because they _might_ be making _assumptions_ that
their code is "_self-documenting_"...

+ Once you are _satisfied_ that the content in the Pull Request is acceptable,
approve the pull request using GitHub's "_Review_" interface. 
![review-changes-submit](https://cloud.githubusercontent.com/assets/194400/22298017/f45fa20e-e316-11e6-8fd6-d9825f5ce682.png) 
> We ***encourage peer-review*** by team-members on ***all*** our projects, 
so it's not _uncommon_ to see _multiple_ people "***approving***" a PR. 
e.g: https://github.com/TheScienceMuseum/collectionsonline/pull/708 
![multiple-reviewers](https://cloud.githubusercontent.com/assets/194400/22298408/54d24b7c-e318-11e6-9009-4b42bba4f5e4.png)

1. ***Merge the Pull Request***.

1. ***Delete The Branch*** on GitHub (_and your local machine_).
The code is now merged into another branch (_most likely `master`_)
so deleting the branch will not "_lose_" any code.

1. ***Finally***, _someone_ on the team
(_usually the developer who created the PR_)
applies the [`please-test` **label**](https://github.com/dwyl/labels/issues/46)
to any issues mentioned in the PR so that the Product Owner and/or
User Testing Team are _aware_ that the feature is ready to test.

2. ***Ideally*** the ***Original Issue Creator*** should post a comment
confirming that the issue (User Story, Question or Problem) has been
adequately addressed and then ***close the issue***.
> In ***practice*** the PO often ends up closing the issue.

# Notes on _Effective_ Contributing

### Thanks for Reading! Please Help Us _Improve_! [![Help Wanted!](https://img.shields.io/badge/help-wanted-brightgreen.svg?style=flat "Please Help Us")](https://github.com/dwyl/contributing/issues)

Thank you for reading _this_ far in this
[_huge_](https://github.com/dwyl/contributing/issues/28) readme!
Please help us by suggesting edits (_we're always happy to remove words!!_)
and improvements!

## _Example_ User-focused "Story" Descriptions

_**User stories** describe features_ (_or "**expected behaviour**")
of the application_ 
in terms of the ***value***
(_or "**benefit**"_) to the ***person using the application***.

Example user story (_if the feature has not been described before_):
 ```
 As a person using the Web App
 I want to be able to save a shortcut app icon to my home screen
 so that I can easily get back into the app without having to navigate to it.
 ```
 
 Or, when you are reporting an issue/bug/fault, try and include
 the exact steps to "_reproduce_" the issue. 
 Example:
 ```
 when using the app on an iPhone 6 running the latest OS (10.2)
 when I attempt to save a shortcut to my home screen,
 I do not see an app icon. :-(
 ```
### Include Any/All _Relevant_ Information in the _Issue Description_

+ Please *include* as much ***relevant information*** as you can
so the Product Owner (_or project leader_)
can ***validate*** that
it is a **necessary/desired** feature.

+ **Note**: A _good_ user story _describes_ the idea
 in a _**concise** and **user-focused**_ way.

+ ***Never*** leave the issue _description_ blank
even when you are in a "rush". 
The point of issues is to _communicate_.
If you see an _incomplete_ issue flag it.
(_Link your friend to here...!_) 
You _wouldn't_ send a _blank email_
to hundreds of your friends (_unless you wanted to freak them out!_), yet, 
submitting ***blank issues*** is doing _exactly_ that!
It sends a ["_I have **no idea** what I'm doing_"](https://www.google.com/search?q=i+have+no+idea+what+i%27m+doing&tbm=isch)
**message** to your ***peers*** ... 
Which was only _amusing_ the _first_ time ... _just_ ***communicate better***.

Example of useful details:
```
People using the app will only access the app from their company-issued
Android (Lollipop) Mobile phone (5 inch Samsung Galaxy J).
The screen resolution is 1080 x 1920 pixels.
```
Or, when describing a specific need for "_offline capability_":
```
People use the app in areas with poor mobile signal,
so the app has to work offline and sync data/changes later
when they are back on WiFi or 3G.
```
Or, when reporting an issue (_potential bug_):
```
People using Windows 8 and Internet Explorer 10 report that
they cannot click on the button to save their app preferences/settings.
```

> ***Tip***: _If you **can upload** a_ ***sketch*** (_of the idea_) or
***screenshot*** (_of the issue_), it helps _clarify_ things a lot! 
> ***How to take screenshot***: https://www.take-a-screenshot.org
(_all platforms_!)

Example creating a **New Issue** for an ***expected behaviour***
with a ***clear description*** and **_illustrative_ screenshots**:

[![create-issue-for-home-screen-icon](https://cloud.githubusercontent.com/assets/24758860/22227322/ae12d9f6-e1c2-11e6-928c-c20cfe8b3912.png)](https://github.com/dwyl/dwyl.github.io/issues/194)

> This is a _real_ issue: https://github.com/dwyl/dwyl.github.io/issues/194
**you _can_ help us _resolve_ it**!

## _Practical_ Note on Time Estimation for a Story/Task

Our time estimates are
usually for a ***pair of people programming together***. 
(_Adjust accordingly if you're working without a pair.
Or, better yet, **find someone** to pair with!_)

Where the team includes _several developers_ the time
estimate will be the _average_ expected time 
for the two _least experienced people_.
Underestimating the expected time for a task out of "_naive optimism_" 
sets an ***unrealistic expectation*** and leads to ***stress & sadness***.

### _Revising_ a Time Estimate

If you are made aware of _any_ reason why the original time estimate
applied to a story is unlikely to be the _actual_ time it's going to take
to complete, inform your team as soon as possible!
Avoid _suffering in silence_ if you are _stuck_ on something just
because you don't want to alter the time estimate!
Nobody will "_hate_" you for being honest about how much effort it _actually_
is taking to deliver the work! Just tell your team
(_by commenting in the issue_) as soon as you know it's
taking longer than expected, and _ask_ for _specific_
help from your "***Scrum Master***" or "**Team Lead**".

### Estimating for _Open Source_ Modules (_without "sprints"_)

For independent open source modules or hobby projects
we **estimate** on an **ad hoc basis _before_ work starts** on the issue. 
Just because we are doing Open Source work does not mean we
shouldn't estimate the expected effort/time for our work. 
If anything we should follow our Contributing Guide ***better***
because our Open Source work is available for ***everyone*** to see! 
Some of our open source modules
are made to solve a problem in a client project/product. 
If you are doing work on an Open Source module during "client work" time,
please "mirror" the issue in the Project and _ensure_ 
you **estimate in _both_ places** so the "PO"
(_AKA approver of invoices!!_)
on the project is _always aware_ of what you are doing.

## _Notes_ on Creating _Good_ Pull Requests

### 1. Keep It Small and Simple (AKA the KISS principle)

+ Don't be _tempted_, to "_bundle_" up _several_ bug fixes/feature additions into
one _large_ PR and then submit it to be reviewed all at once... 
We prefer working in _smaller increments_ splitting the work
into individual parts to be reviewed separately. 
> _Why_...? Read: "***Work in Small Batches***": https://www.startuplessonslearned.com/2009/02/work-in-small-batches.html

+ The _best_ PRs **update the documentation** (often the repo's README file)

+ ***Always*** _ensure_ there are **passing tests** for any new code you have written.

### 2. _Descriptive_ Pull Request Title and Description!

+ A **descriptive title** answers the question:
"_What is **included** in this PR_?"

+ A ***good description*** summaries the _contents_ of the PR and
gives the person/people reviewing the PR
a **clear picture/focus** for the feature/change/bug-fix
which ***improves review speed***.

+ ***Reference*** the issue(s) that the PR addressed in the PR description.

### 3. PR _Etiquette_

+ Explain what the PR includes (**bullet pointed lists**
  are sometimes helpful to make things clearer)
  and the _implementation detail_.

+ If you have the _permissions_ to do so,
**assign your pull request**
to someone (_else_) for review.

+ ***Never*** merge your _own_ pull requests on a **_team_ project**.
**No Exceptions**. Just ***don't do it***.

A good example PR: https://github.com/indexzero/ps-tree/pull/12
created from the ***need***
which was ***validated*** and ***discussed*** in
an **issue** https://github.com/indexzero/ps-tree/issues/10
***before*** _any_ work was performed.

## Creating a New repository

### Use Cases for Creating a New Repo
+ You have search through dwyl's _existing_ repositories and have not found one
that covers the subject that you want to **share your knowledge** on.
+ You want to build a new open source application/module/tutorial that you
believe is in line with dwyl's [values](https://github.com/dwyl/start-here/blob/master/manifesto.md)
and will _benefit the community_.

### How?
1. **Open an issue** in [dwyl/start-here](https://github.com/dwyl/start-here)
explaining the _Why?_ and _What?_ of the repo you want to create.
2. **Wait for your issue to be validated** by the community - in the same way we
handle other issues. It may be that someone is already working on something similar
in a repo you haven't seen yet. Or, it may be something that dwyl tried in
the past but moved away from.
3. If the need is validated, **create the repo** following the _[requirements](#minimum-requirements-for-a-new-repository) below_.

### Minimum Requirements for a New Repository
Everyone's busy and we know that sometimes repositories are created with great
intentions but people don't have time to look at them for a few days or weeks.

These minimum requirements when creating a repo mean that the intention is clear
and contributions from the open source community can begin early.

+ [ ] Initiate the repo _with_ **a clear description**
+ [ ] Initiate the repo _with_ a README
+ [ ] Add dwyl's standard labels by using https://label-sync.herokuapp.com
+ [ ] Add a [CONTRIBUTING.md](https://github.com/dwyl/contributing/blob/master/CONTRIBUTING.md) file to the repo
+ [ ] Update the README.md with simple 'Why?', 'What?' and 'How?' sections
+ [ ] [Protect the `master` branch](https://help.github.com/articles/about-protected-branches/)
 to ensure it can't be pushed to directly
+ [ ] If relevant, add the right people/teams to the repo as collaborators

## Forking Repositories into dwyl
Generally, forking a repository _into the dwyl organisation_ is **not required**, or
recommended, without good reason as forks carry an additional maintenance burden
and have issues _disabled_ by default (voiding our contributing process).
The _only_ reason to do so is if you're planning to fix an issue in the original
repo and **send a patch/PR back up-stream** to that original repo.

If you would like to _transfer ownership_ of one of your repositories to the dwyl
organisation, please **open an issue** in [dwyl/start-here](https://github.com/dwyl/start-here).

## General Notes

### Images and Binary Files

When making a pull request, make sure that you haven't included
any ***unnecessary*** files that will take up a lot of space in the project!

Such files include images and other binary files like dependencies or drivers.
Git is meant for source code and other (_text-based_)
files that require version control.
Images and other binary files are difficult for a human to review
in a GitHub Pull Request and just take up a huge amount of space!
This means that when ever a person clones/pulls the code they have
to _download_ many/huge files
(_not just the code which is typically tiny by comparison_)

> It is a _general_ `git` "_best practice_" to avoid _clogging_ up your
Git repo with files that don't need to be under version control.

### Inspired By

Guidelines for creating user stories are adapted from
[Simon's](https://github.com/simonlab)
[**user-story-checklist**](https://github.com/SimonLab/user-story-checklist)
repo. Check it out! :heart:

### Labels

GitHub can be a [_great_ project management tool](https://github.com/dwyl/github-reference#why) if used _effectively_ and _labels_ are a great way to **organise** and **track** the progress of a
given project at any point in time.
They are a fantastic **communication tool**, particularly for [remote teams](https://github.com/dwyl/remote).

At dwyl we have created our _own_ standard list of labels
that we use for each of our projects. This gives our team the ability
to move between projects **quickly** and **productively**, saving time
and energy in the process.
> For our [**Complete List of Labels**](https://github.com/dwyl/labels/labels)
and how they should be used, take a look at https://github.com/dwyl/labels.

## Additional Information

We are releasing our work under the GNU General Public License Version 2 (GPL V.2)
if you have any questions regarding the license, please read:
https://github.com/dwyl/intellectual-property and raise an
[issue](https://github.com/dwyl/intellectual-property/issues)
on GitHub if you require clarification!

# Got a _Security/Privacy_ Concern or Question ?

If you have a [***security/privacy***](https://github.com/dwyl/learn-security)
_related question_ that you want to ask or ***disclose discreetly***, 
**_please_ email** us:
[**hello+security@dwyl.com**](mailto:hello+security@dwyl.com) 
_For **all other questions/ideas/issues, please follow** the **normal steps**_.
***Thanks***!

[![HitCount](https://hits.dwyl.com/dwyl/contributing.svg)](https://hits.dwyl.com/dwyl/contributing)

contributing

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

contributing

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README