search

dwyl / contributing

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

readme

welcome-teal

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:

validate-idea

Please inform us if anything is unclear or if you have a suggestion for how to simplify/streamline it! Get Help!

Contents Guide

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 that everyone can easily see!

Step 1: Check if the Question/Idea/Story/Issue Already Exists Using GitHub Search search

  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...)

  2. 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

  3. 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

  4. 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

  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

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". We think of issue validation as something that:

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

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

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.

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

  3. (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

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

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!

Please See below for "Practical Notes on Time Estimation".

Step 2: Assign Yourself the Task and Do it!

  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" 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

  4. Log progress as comments in the issue 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!)

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" 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 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)

  2. 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.

  3. 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.

  4. Review the content (documentation, tests, or code) in the Pull Request on GitHub...

  5. 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!

    • 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"...

  1. Merge the Pull Request.

  2. 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.

  3. Finally, someone on the team (usually the developer who created the PR) applies the please-test label 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.

  4. 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!

Thank you for reading this far in this huge 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

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

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)

2. Descriptive Pull Request Title and Description!

3. PR Etiquette

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

How?

  1. Open an issue in 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 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.

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.


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 user-story-checklist repo. Check it out! :heart:

Labels

GitHub can be a great project management tool 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.

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 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 on GitHub if you require clarification!

Got a Security/Privacy Concern or Question ?

If you have a security/privacy related question that you want to ask or disclose discreetly,
please email us: hello+security@dwyl.io
For all other questions/ideas/issues, please follow the normal steps. Thanks!

HitCount