Drasil: Create Contributor's Guide Wiki

[smiths]

@niazim3, can you please create a wiki page that can act as a Contributor's guide for Drasil. @JacquesCarette had some good advice for pull requests (one feature at a time, self-contained, passes tests, etc.). It would be great to capture this information for the summer students/graduate students this year and for future summer students/grad students. @JacquesCarette has also sent out several messages that should be captured for the future, like the one about cherry picking. To get an idea of what other projects contributor's guides look like, you can google the term. For larger projects the contributors guides can get very large and involved. We don't need that. A few pages should be good. We are just trying to capture best practices for our project. You also don't need to aim to "teach" the best practices, but pointers (links) to useful resources would be great.

This is another task that you can fit in while you are waiting for feedback on a pull request, or some other guidance from @JacquesCarette, @szymczdm or myself.

[niazim3]

Contributor's-Guide

[smiths]

@niazim3, I just had a look at the current draft of the Contributor's Guide. Good start! I like that you have pointers to resources (like Haskell, Drasil papers etc) that you started with. Also the "roadmap" you have at the start is a good idea. Readers will need this to decide what part of the guide applies to them.

[niazim3]

Since the file for the book chapter that gives an overview of rational documentation for scientific software is in GitLab (sent in the "Getting Started" email to the summer research assistants), should it be in the Contributor's Wiki? Asking since the GitLab we work with is only for McMaster students and Drasil is a public repo...

[smiths]

You should minimize the links to private resources, but if it is necessary, please include the link. The main audience (at this time only audience) for this documentation will be people that have access to the gitlab repo. The overview of rational documentation for scientific software is a useful resource, and there is no publicly available equivalent. If you want to get really fancy, you could include a link to where an interested reader can get/purchase a version. For the resource in question, I guess this would be a link to the CRC press book that published the scientific software resource.

[niazim3]

https://help.github.com/articles/setting-guidelines-for-repository-contributors/ this may be something that we want to either convert the wiki page into or link very specific info from the wiki to. It would also contribute to this repo's community profile
.

[smiths]

I really like this idea. Following standard github practice for the contributors guide makes complete sense to me. I think we should move the wiki content into a CONTRIBUTING.md file. I think it makes the most sense to locate this file in root, but @JacquesCarette or @szymczdm may have a different idea. Once we have conferred with them, we can start developing the contributor's guide in the CONTRIBUTING.md file instead of on the wiki.

[smiths]

@niazim3, in the contributor's guide, can you please add text to remind contributors that any changes should be "physics knowledge preserving." We have had issues where the easiest solution to get some particular knowledge into the DSLs for Drasil was to simplify the knowledge. In particular, in some cases assumptions, sources, derivations and links to other definitions have been removed. There is some "filler" information in the manual documentation, but almost everything in there is there for a reason. It might not always be a good reason, but changes that remove physics should not be made unilaterally. A discussion is necessary in all cases.

[smiths]

@niazim3, can you please add a section to the Contributor's Guide on creating a good issue. You, @samm82 and @elwazana write excellent issues. You include enough information that the reader can respond to the issue without having to track down multiple sources. Including excerpts of the pdf documentation, especially annotated excerpts, is really helpful. The frequent use of links to related issues and commit numbers is also really helpful. Future contributors would benefit from you sharing what you have learned about writing issues.

[smiths]

@niazim3, information on when to increase the version number would also be good content for the contributor's guide. @samm82 can likely help with this.

[samm82]

@smiths Do you think this issue can be closed since the guide has been created, and we've since been creating separate issues for adding more information to it?

[smiths]

Yes, you are correct that this issue has been split into separate issues. We can close this instance.