diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cad61d60..9f41c523 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,10 @@ > This document is inspired by [elasticsearch/CONTRIBUTING.md](https://github.com/elastic/elasticsearch/blob/master/CONTRIBUTING.md) +Adding a `CONTRIBUTING.md` to a github repository enables a link to that file in the pull request or create an issue page. This shows potential contributors how to make a meaningful impact on the project. Contribution guidelines save time and hassle caused by improper pull requests and issues. You can learn more about the features that are enabled by github when this file is present [here](https://help.github.com/articles/setting-guidelines-for-repository-contributors/) + +## How to contribute + There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, [submitting github issues](https://help.github.com/articles/creating-an-issue/), bug reports, feature requests and writing code. ## License @@ -31,13 +35,13 @@ For small documentation changes and fixes, these can be done quickly following t ### Cloning (or forking) the repository -First off, you are going to need your own copy of the repository. You can find help on how to fork a repo [here](https://help.github.com/articles/fork-a-repo/). +First off, find help on how to fork a repo [here](https://help.github.com/articles/fork-a-repo/). -### Submitting your changes +### Submitting changes -1. Review & Test your changes +1. Review & Test changes -If it's code: make sure you test it. If it's documentation: make sure you view it in a Markdown viewer or the like. +If it's code: test it. If it's documentation: make sure to view it in a Markdown viewer or the like. 2. Commiting @@ -51,7 +55,7 @@ Make sure you've signed the repository's Contributor License Agreement. We are n 4. Submit a pull request -Push your local changes to you forked repository and make a pull request. Follow the [Convention Commits](CONVENTIONAL_COMMITS.md) guidelines for naming Github pull requests and what to put in the body. +Push local changes to you forked repository and make a pull request. Follow the [Convention Commits](CONVENTIONAL_COMMITS.md) guidelines for naming Github pull requests and what to put in the body. ## Building diff --git a/README.md b/README.md index 9f3e0144..2c4edc45 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,18 @@ # Pristine -Pristine is an open source repository in its original condition. It is meant to be a starting point and a place to find resources to augment your own open source repositories. +Pristine is an open source repository in its original condition. It's goal is to be a starting point for open source repositories wanting to follow Documentation Driven Development. It is also a place for existing projects to find resources to augment current documentation. +## Documentation Driven Development + +There are many ways to drive development but with open source specifically, starting at the README gives a middle ground between technical specifications and non-technical. This promotes open source contribution and engagement. + +> By the same principle a beautifully crafted library with no documentation is also damn near worthless. If your software solves the wrong problem or nobody can figure out how to use it, there’s something very bad going on. + +- [Readme Driven Development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html) by Tom Preson-Werner ## Getting Started -To get started, you will need a [fork of the repository](https://help.github.com/articles/fork-a-repo/). Then you can edit this file and delete everything above this line. +To get started, [fork](https://help.github.com/articles/fork-a-repo/) or [duplicate](https://help.github.com/articles/duplicating-a-repository/) the repository. Then edit this file and delete everything above this line. --- @@ -14,8 +21,8 @@ To get started, you will need a [fork of the repository](https://help.github.com Using conventions and specifications make it easier to: - build and use composable tools - ease onboarding -- promote contribution -- promote issue and feature discussion +- promote contribution and engagement +- promote issue and feature discussion on github itself ### Contributing @@ -25,7 +32,17 @@ How to contribute, build and release are outlined in [CONTRIBUTING.md](CONTRIBUT #### Docker: -Docker is used as a building block. Here are the resources you need to get started and install docker: +Docker is used as a building block. Here are the resources needed to get started and install docker: - [Install Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/) - [Install Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/) + +#### Resources + +- [Readme Driven Development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html) +- [pengwynn/flint](https://github.com/pengwynn/flint) +- [Working Backwards](https://www.allthingsdistributed.com/2006/11/working_backwards.html) +- [Literate programming](https://en.wikipedia.org/wiki/Literate_programming) +- [Hammock Driven Development](https://www.youtube.com/watch?v=f84n5oFoZBc) +- [Inversion and The Power of Avoiding Stupidity](https://fs.blog/2013/10/inversion/) +