Contributing
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:
- Part 1: Describe your Question, the Idea or User Story in an Issue
- What do I do next?
- Part 2: Validate the Need (User Story) or Issue Exists
- Part 3: Do the Work!
- Example User-focused "Story" Descriptions
- Practical Note on Time Estimation for a Story/Task
- Notes on Creating Good Pull Requests
- Creating a New Repository
- Forking Repositories
- General Notes
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 the truth
that everyone can easily see!
-
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...) -
Try searching through the existing issues for keywords associated with the story/issue you want to create,
e.g: https://github.com/dwyl/time/issues?utf8=%E2%9C%93&q=is%3Aissue%20app+icon
if"app icon"were the keywords for what you have in mind and you were searching in the "Time" project.
-
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 if 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 new issue.
- 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!)
- Using the
New Issuebutton, 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!
-
Submit the new issue!
-
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.
-
That's it from the side of the issue creator! (thank you!)
Once a new issue has been created, it must be "validated" by a different member of the team/organisation. (see: "Part 2" below...)
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! 🌟
This may initially feel a bit "bureaucratic" but
we urge you not to think of it as
"jumping through hoops"
but rather, we think of issue validation as:
-
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 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!
e.g: if you have a question or are stuck on a challenge/problem, share your thoughts and/or progress towards "solving" it in issue comments 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!
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.)
-
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 helpwhileyou 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
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".
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, and reserve the word "bug" for when a reported issue 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
buglabel until the issue has been validated.
A different team member from the person who created the issue must validate the User Story/Issue.
-
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. -
The person acknowledging the user story will add some labels to the issue to help categorise it. eg.
question,discuss, etc. -
(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
- 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-2to 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.
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!
- For an ongoing project, we estimate stories
During "Sprint Planning" session;
A time estimate label (e.g:T4horT25m) 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!
-
Assign the story/issue to yourself before you start working.
-
Apply the
in-progresslabel to the story/issue/sub-task so that your team knows when work started and that it is currently being worked. -
Update the
README.mdbefore 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, ask yourself remind yourself of the last time you "inherited" undocumented code...)
Watch: "The Mess We're In" by Joe Armstrong
- 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-progresslabel and un-assign yourself form the story.
-
Reference the user story/issue/sub-task you are working on by pasting a link to the GitHub issue in the commit message.
-
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.
Rule (of thumb): Keep Pull Requests Small and Focused.
-
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.
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
READMEto explain the latest changes made (or explain specifically why you haven't had to update theREADME). -
Increment the version of your application if it is a "new release".
-
Remove the
[WiP]from your PR title. -
Remove the
in-progresslabel from the PR and associated issues. -
Apply the
awaiting-reviewlabel to the PR. -
Assign someone
elseto 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!)
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:
-
Apply the
in-reviewlabel 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) -
Checkout the PR's branch and run it on your local machine following the instructions in the
README.mdwhere applicable.
Confirm the tests pass and app runs on your local machine.
-
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.
-
Review the content (documentation, tests or code) in the Pull Request on GitHub...
-
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
-
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, approve the pull request using GitHub's "Review" interface.
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
-
Merge the Pull Request.
-
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. -
Finally someone on the team (usually the developer who created the PR) applies the
please-testlabel 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. -
Ideally the Original Issue Creator should post a comment confirming that the issue (User Story, Question or Problem) has been adequately address and then close the issue.
In practice the PO often ends up closing the issue.
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!
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 if 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. :-(
-
Please include as much relevant information as you can so the Product Owner (or project leader)
can validate if 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" 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 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 for a 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 a lot!
How to take screenshot: http://www.take-a-screenshot.org (all platforms!)
Example creating a New Issue for an expected behaviour with a clear description and illustrative screenshots:
This is a real issue: https://github.com/dwyl/dwyl.github.io/issues/194 you can help us resolve it!
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.
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".
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.
- 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":
http://www.startuplessonslearned.com/2009/02/work-in-small-batches.html
-
The best PRs update the documentation (often the repo's readme)
-
Always ensure there are tests for any new code you have written.
-
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.
-
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.
- 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 and will benefit the community
- Open an issue in dwyl/start-here explaining the Why? and What? of the repo you want to create
- Wait for the need to be validated by the community - in the same way we operate with 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 has tried in the past but moved away from for a specific reason that you can be pointed to
- If the need if validated, create the repo following the requirements below.
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 http://label-sync.herokuapp.com
- Add a CONTRIBUTING.md file to the repo
- Update the README.md with simple 'Why?', 'What?' and 'How?' sections
- Protect the
masterbranch to ensure it can't be pushed to directly - If relevant, add the right people/teams to the repo as collaborators
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.
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.
Guidelines for creating user stories are adapted from Simon's user-story-checklist repo. Check it out! ❤️
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.
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.
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!
If you have a security/privacy
related question that you want to ask or disclose discreetly,
please email us:
[email protected]
For all other questions/ideas/issues, please follow the normal steps.
Thanks!
