Creates a contributing.md document #148
Conversation
|
|
||
| When considering submitting a new analysis to American Gut, you should begin by posting an issue on [the American Gut Issue Tracker](https://github.com/biocore/American-Gut/issues). The information which needs to be included in this post will differ based on the type of contribution. Your contribution will also need to be tested (discussed below). | ||
|
|
||
| * For new features, describe why the functionality being proposed is relevant. The functionality must be demonstrated as relevant to other users, or other analyses. If appropriate, you may be encouraged to push the functionality to other biocore packages, such as [QIIME]() or [scikit-bio](). |
There was a problem hiding this comment.
the links to QIIME and scikit-bio are not present
|
credits and license section, and below, still don't render right. suggest checking out how github renders: https://github.com/JWDebelius/American-Gut/blob/contributing/CONTRIBUTING.md |
jwdebelius
changed the title
jwdebelius
changed the title
|
@wasade @EmbrietteH: I think I have the formatting issues fixed. |
|
Previously for references we just used hyperlinks... why the change? |
|
A more complete citation lets you know what you're looking at. Also, if you're linking out to a webpage that has since been take down, the description makes it easier to find that information |
|
Right, but we've previously been linking to the Pubmed PMID which is On Thu, Oct 29, 2015 at 4:11 PM, J W Debelius [email protected]
|
|
For me, the first issue is the bigger one. I tend to get frustrated with the inline link-style citations following sentences, but typically read through numbered citations unless I want to follow up. Numbers also mean that I know you're referencing the same thing multiple times. But, ultimately, it's a stylistic question. |
|
|
||
| * For new features, describe why the functionality being proposed is relevant. The functionality must be demonstrated as relevant to other users, or other analyses. If appropriate, you may be encouraged to push the functionality to other biocore packages, such as [QIIME](https://github.com/biocore/qiime) or [scikit-bio](https://github.com/biocore/scikit-bio). | ||
|
|
||
| * For new analyses, you’ll want to describe the new approach. Explain why you have selected this approach, citing as necessary. Your analysis should be presented as an Jupyter Notebook (see below). |
There was a problem hiding this comment.
What do you think about adding an external link to Jupyter Notebook?
There was a problem hiding this comment.
I can, but that was actually a reference to the discussion section about Jupyter notebooks, below...
There was a problem hiding this comment.
Just saw that :S
Ok. No biggie. No strong preferences for adding another link.
On Mon, Nov 16, 2015 at 9:27 AM, J W Debelius [email protected]
wrote:
In CONTRIBUTING.md
#148 (comment):@@ -0,0 +1,152 @@
+# Contributing to American Gut
+
+The American Gut Project is the largest a crowd-funded science project looking to map the topology of the human superorganisms. One of the goals of the American Gut Project is transparency about data processing and technique development. You can find source code used in American Gut analyses under public revision in the American Gut Repository on Github.
+
+This document covers what you should do to get started contributing to American Gut. You should read this whole document before you consider submitting code to American Gut. This will save time for both you and the American Gut developers.
+
+## Types of Submissions
+We are looking for submission of new analyses (although it may be a good idea to discuss your analysis with the development team before submitting your pull request), bug fixes, documentation updates, additions, and fixes.
+
+When considering submitting a new analysis to American Gut, you should begin by posting an issue on the American Gut Issue Tracker. The information which needs to be included in this post will differ based on the type of contribution. Your contribution will also need to be tested (discussed below).
+
+* For new features, describe why the functionality being proposed is relevant. The functionality must be demonstrated as relevant to other users, or other analyses. If appropriate, you may be encouraged to push the functionality to other biocore packages, such as QIIME or scikit-bio.
+
+* For new analyses, you’ll want to describe the new approach. Explain why you have selected this approach, citing as necessary. Your analysis should be presented as an Jupyter Notebook (see below).I can, but that was actually a reference to the discussion section about
Jupyter notebooks, below...—
Reply to this email directly or view it on GitHub
https://github.com/biocore/American-Gut/pull/148/files#r44953726.
|
One potential problem with Pubmed IDs is not all publications have Pubmed IDs. Not sure if this will be an issue here ... Having complete citations seems appropriate - no strong preferences here. What needs to be done to get this merged? |
|
The PMID thing isn't necessarily an issue, if we use citations. At this point, there needs to be a concensus on the citation style. Perhaps, @EmbrietteH has a suggestion? Alternatively, if @wasade agrees, we could use citations moving forward, and include a note that historic notebooks do not necessarily adhere to these standards? |
|
My concern is that if the contributing requirements are too ridged, either
|
|
I'd rather have the standards, and not have people adhere to the letter than leave ambiguity. |
|
What about doi? Even if there is no PMID, everything has a doi.... Sent from my HTC on T-Mobile 4G LTE ----- Reply message ----- The PMID thing isn't necessarily an issue, if we use citations. At this point, there needs to be a concensus on the citation style. Perhaps, @EmbrietteH has a suggestion? Alternatively, if @wasade agrees, we could use citations moving forward, and include a note that historic notebooks do not necessarily adhere to these standards? Reply to this email directly or view it on GitHub: |
|
That was part of a discussion about link stability. I was advocating for a Daniel was arguing for links in the text, and that because most of what was I'm against DOI as a citation mechanism for what is primarily biological On Mon, Nov 16, 2015 at 10:05 AM Embriette Hyde [email protected]
|
|
PMID and DOI both provide stable links to the original article and will avoid endless additional threads about reference styles and compliance. Suggest using PMID if available, DOI if not (or maybe always DOI with PMID as available?)
|
| ### Discussion or Conclusions | ||
| The notebook should end with a discussion of the relevant results. Depending on the style of the notebook, it may be more appropriate to do result-by-result discussion. In that case, a short conclusion or prospectus should be provided. | ||
|
|
||
| ### References |
There was a problem hiding this comment.
We settled for DOI links correct? May want to update this
|
Can this be merged? |
|
The document seems to be a moving target. It seems like based on the meeting on Tuesday, we were changing how we wanted to handle things like environments. So, this can be merged, it can be closed and updated with the current best practices... |
|
is it accurate with respect to our own use of the repository though? i think this repo needs a lot of clean up and organization first. |
|
I don't think it's currently accurate. I don't know that it's every been accurate, especially given the primary processing set up. |
Addresses issue #147. This is a first pass, roughly based on the sckit-bio contributing.md.
There are a few issues which need to be addressed here: