Add CONTRIBUTING.md

[pdurbin]

As discussed at http://irclogs.jackgrigg.com/irc.freenode.net/openhatch/2015-03-15#i_3596011

16:08 shauna Also, we have a lot of labels (https://github.com/openhatch/oh-mainline/labels) but none of them seem to be "accepted" or "needs help"
16:08 pdurbin shauna: is there a guide to the labels used by openhatch?
16:08 shauna No. There should be, shouldn't there?
16:09 shauna I wish github allowed you to pin a link to the top of the issue tracker.
16:09 shauna I'm not sure where the guide should go, otherwise. Bury it in the documentation?
16:09 shauna Well there's this: https://openhatch.readthedocs.org/en/latest/internals/issue_tracking.html?highlight=issue
16:09 shauna Could be expanded, it's very sparse right now.
16:29 pdurbin shauna: I have an idea for you around this if you have a moment for me to show you.
16:29 shauna Sure
16:32 pdurbin shauna: please compare https://github.com/openhatch/oh-mainline/issues/new to https://github.com/IQSS/dataverse/issues/new
16:32 pdurbin see how the latter says "Please review the guidelines for contributing to this repository" with a link?
16:36 pdurbin shauna: (you don't have to actually create an issue to see what I'm talking about. you just have to start the process, to bring up the form)
16:37 shauna Oh, that's neat.
16:37 shauna How did you set that up?
16:38 pdurbin shauna: it's described at https://help.github.com/articles/setting-guidelines-for-repository-contributors/ and https://github.com/blog/1184-contributing-guidelines
16:38 pdurbin in short, you add a CONTRIBUTING.md file to the root of your repo
16:38 shauna Very cool. We should do that.
16:38 shauna Want to file an issue?
16:39 pdurbin It's where we describe our issue labels: https://github.com/IQSS/dataverse/blob/master/CONTRIBUTING.md#issue-labels

[moijes12]

@pdurbin @willingc I'd like to work on this. Can I get some pointers on how to start ?

[ehashman]

Hi @moijes12, I recommend you take a look at the last link in the IRC conversation (this one). That is the kind of document this issue would like to see created!

All you need to do is create a Markdown file called CONTRIBUTING.md in the root of the repository with our contribution guidelines. I think this page might be a good place to start.

@shaunagm, I'm curious what you'd like to see on this page as you raised the issue :) Re: labels, I mostly use them to help reference bugs that affect different parts of the site, plus triage level and status, but I could write some specific things about each label I use/have created.

[moijes12]

We do have a list of things to do before submitting code and that is maintained Here

However, if we are to add information on issue labels and documentation, I think we could do by using a content structure similar or even identical to that seen at dataverseorg's Conrtibuting.md.

What else should we add in here ?

[moijes12]

Contributing to OpenHatch

Yay! Its great that you want to contribute to the OpenHatch.org website. We look forward to receiving your contributions in code, feature requests and bug reports. Here are pointers and guidelines that we feel you should follow before creating your pull request, bug report or feature request.

Code Contributors Guide

OpenHatch.org has created good documentation for anyone who may want to hack on the website and to help new developers get up to speed. This contributor's guide is available Here

Pull Requests

How we handle code contributions is well explained in this this page. The steps to be followed by both Contributors and Reviewers are nicely documented.

Feature Requests And Bug Reports

All feature requests and bug reports are created as new issues on the issue tracker. Before creating a new issue, please consider reading through the list of open issues to be sure they haven't already been raised. In case you find that one has already been raised, feel free to add a comment to it.

Creating Bug Reports

You've found an error on the site? The community is here to help. Go ahead and create a new bug report if it there isn't one for it already. We'd love it if you would also:

• Label the issue with priority pri:bug (see the section on Issue Labels)
• Add a screenshot of your browser
• Tell us what web browser you were using and the version of the browser (You would find this under the "About" section of your browser's Help e.g. Help->About Firefox)
• Tell us what OS you're using
• If you can, add labels letting us know where you think the issue would be, for example, CSS or JavaScript etc.

Bug reports for developer documentation are also tracked in the same issue tracker.

Creating Feature Requests

If there's a feature you'd like to see in the OpenHatch.org website, go ahead an create a feature request. To do that, simply:

• Click on the New Issue button
• Detail the feature in the new issue
• Label the issue with priority a pri:feature

The community will work and take things forward.

Issue Labels

The issue tracker for oh-mainline (the github repository which maintains the code) primarily makes use of the below labels:

• Priority:
  • pri:bug A bug on the website
  • pri:urgent A bug that needs urgent attention by the core developers
  • pri:critical A bug that needs to be fixed on priority and who's fix is critical to the smooth functioning of the website
  • pri:feature A feature request
• Status:
  • stat:chatting: The issue is being discussed by members of the community
  • stat:in-progress: A developer is actively working on it
  • stat:needs-review: A pull request is created and the contribution needs to be reviewed

[ehashman]

One thing I would mention is that we probably shouldn't duplicate information that's in the docs in this file. I think it is better to add a link to the contributor guide in readthedocs than it is to have to maintain the information in two places :)

[shaunagm]

I mostly agree with you, Elana, but I think it's useful to pull out & highlight information specifically related to reporting and responding to issues here. There's also some useful information that's not in the docs, for instance what the different labels mean.

ps @ehashman We miss you at sprints but please go enjoy AdaCamp!

[shaunagm]

An updated set of issue labels, thanks to malidzos:

Issue Labels

The issue tracker for oh-mainline (the github repository which maintains the code) primarily makes use of the below labels:

css: An issue related to a css file (the looks and description of a document)
documentation: Improving or creating the needed documentation.
missions: Issues related to training missions section on the openhatch site.
tests: Issues related to existing tests or demands for new ones.
usability: Issues related to the ease of use, in general.

Milestone:
These relate to timelines for fixing issues. We no longer use them, so just ignore them.

Priority:
pri:bug A bug on the website
pri:feature A feature request on the website
pri:urgent Needs urgent attention by the core developers
pri:critical Needs to be fixed on priority and who's fix is critical to the smooth functioning of the website
pri:wish Will be awesome to have eventually but no urgency.

Status:
stat:chatting: The issue is being discussed by members of the community.
stat:deferred: The issue is being postponed, so don’t work on this issue.
stat:in-progress: A developer is actively working on it.
stat:needs-decision: A question has been raised and a decision needs to be made before progress on the issue can continue.
stat:needs-review: A pull request has been created and the contribution needs to be reviewed
stat:reopened: An issue that is being inspected again.
stat:resolved: Issues that have been fixed.
stat:unread: No maintainer has read this issue, so check before working on it.

[ehashman]

I updated "needs-decision" in your comment above because it was easiest to change it inline :)

+1

[moijes12]

Contributing to OpenHatch

Yay! Its great that you want to contribute to the OpenHatch.org website. We look forward to receiving your contributions in code, feature requests and bug reports. Here are pointers and guidelines that we feel you should follow before creating your pull request, bug report or feature request.

Code Contributors Guide

OpenHatch.org has created good documentation for anyone who may want to hack on the website and to help new developers get up to speed. This contributor's guide is available Here

Pull Requests

How we handle code contributions is well explained in this this page. The steps to be followed by both Contributors and Reviewers are nicely documented.

Feature Requests And Bug Reports

All feature requests and bug reports are created as new issues on the issue tracker. Before creating a new issue, please consider reading through the list of open issues to be sure they haven't already been raised. In case you find that one has already been raised, feel free to add a comment to it.

Creating Bug Reports

You've found an error on the site? The community is here to help. Go ahead and create a new bug report if it there isn't one for it already. We'd love it if you would also:

• Label the issue with priority pri:bug (see the section on Issue Labels)
• Add a screenshot of your browser
• Tell us what web browser you were using and the version of the browser (You would find this under the "About" section of your browser's Help e.g. Help->About Firefox)
• Tell us what OS you're using
• If you can, add labels letting us know where you think the issue would be, for example, CSS or JavaScript etc.

Bug reports for developer documentation are also tracked in the same issue tracker.

Creating Feature Requests

If there's a feature you'd like to see in the OpenHatch.org website, go ahead an create a feature request. To do that, simply:

• Click on the New Issue button
• Detail the feature in the new issue
• Label the issue with priority a pri:feature

The community will work and take things forward.

Issue Labels

The issue tracker for oh-mainline (the github repository which maintains the code) primarily makes use of the below labels:

• Priority:
  • pri:bug A bug on the website
  • pri:urgent A bug that needs urgent attention by the core developers
  • pri:critical A bug that needs to be fixed on priority and who's fix is critical to the smooth functioning of the website
  • pri:feature A feature request for the website
  • pri:wish A feature request for the website
• Status:
  • stat:chatting: The issue is being discussed by members of the community
  • stat:deferred: The issue is being postponed, so don’t work on this issue.
  • stat:needs-decision: A question has been raised and a decision needs to be made before progress on the issue can continue.
  • stat:needs-review: A pull request is created and the contribution needs to be reviewed
  • stat:reopened: An issue that is being inspected again.
  • stat:resolved: Issues that have been fixed.
  • stat:unread: No maintainer has read this issue, so check before working on it
• Components:
  • css: An issue related to a css file (the looks and description of a document)
  • documentation: Improving or creating the needed documentation.
  • missions: Issues related to training missions section on the openhatch site.
  • tests: Issues related to existing tests or demands for new ones.
  • usability: Issues related to the ease of use, in general.
• Special Labels
  • bitesize: Small, self-contained issues that are good for new contributors. Warning: they may not be as bitesize as we thought, so please ask for help if you need it! Good questions to ask yourself or a community member include: "How will I know when the issue has been fixed?" "Where should I make my changes?" "Will I need to update documentation or tests?" "What tools or skills are needed to address this issue?"
  • mentor-available: Mentors are available for nearly every task if you ask around enough, but these tasks have a particular person who is enthusiastic about mentoring somone on that task. Mentors should leave a comment saying they want to mentor the task. Whoever assigns the label "mentor-available" is assumed to want to mentor.

[moijes12]

The above comment is an update to my the previous draft. @shaunagm , I have added malidzos' changes in the above update. If everyone is ok with it, then I will go ahead and raise a PR for this.

[malida]

no objections :)

[willingc]

Nicely done @moijes12 and @malida. @moijes12, please submit a PR 🐧

[shaunagm]

I've added descriptions of the bite-size label and the mentor-available label as well. :)

[moijes12]

@shaunagm Thanks! Added your updates to the PR.