search

spacetelescope / style-guides

An opinionated guide on how we work.
Creative Commons Attribution 4.0 International
55 stars 33 forks source link

Style guide for code contributors? #73

Closed pllim closed 4 years ago

pllim commented 5 years ago

Maybe this is not feasible as the contribution process can differ project by project. I was thinking something like http://docs.astropy.org/en/latest/development/workflow/development_workflow.html but more attuned to spacetelescope org. The goal is to provide someone a guideline in contributing to a project that they are not familiar with. This would go well with, say, a PR review guideline that @brechmos-stsci will open a PR for shortly.

Example (and fictional) use case: A STScI instrument scientist who found a bug in stsci.tools, figured out a patch, and wish to contribute for the first time.

Currently, https://github.com/spacetelescope/stsci-package-template/blob/master/CONTRIBUTING.md simply asks the interested party to contact package maintainers.

eteq commented 5 years ago

I'm not 100% sure on this but I think maybe it's best for this to be subsumed into #74 ? In my review there I suggested that this guide is better done as a unified "for reviewers and contributors" document, as it's better if everyone's on as equal footing as possible.

But it might be that this contributor guide should have more detail like "here's how to do a rebase", while #74 is more high-level? So then the prerequisite to the guide this is about would be #74, but it would have more detail?

eteq commented 5 years ago

As a reminder: addressing this should also address https://github.com/spacetelescope/style-guides/pull/74#discussion_r253685000 and one of the links in #74. That is, the code review guide should be referenced from any guide that addresses this issue, and the code guide links should also be updated to point to this issue's guide.

pllim commented 5 years ago

I am not opposed for this issue to be addressed as a follow up of #74 on that same page. @brechmos-stsci , what do you think?

brechmos-stsci commented 5 years ago

I, personally, think the style guides should remain "on topic" and "short". That way people (like me) will read them :). So, given that, I think these two should be separate.