feature: build target file names + release order

Author: shanejonas

BUILDING.md

@@ -1,4 +1,4 @@
-# Project Building
+# Building
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here.
 
@@ -10,30 +10,34 @@ When using the name 'version' we mean the versioning scheme described in [VERSIO
 
 This document is to describe the functionality a project MUST provide in terms of creating build artifacts. It also describes the structure in which project's MUST write build artifacts in.
 
-We propose:
+a project MUST provide:
+
  - a folder name convention for build artifacts
  - a folder structure for the above-mentioned build artifacts folder
- - a list of platforms we will target
- - Using docker-compose with a service for each build target
+ - a list of targets
+ - a file called `bin/build.{target}.{ext}` to target each of the build targets
  - a build pipeline given the above pretext
 
 The purpose of having a uniform way of producing a build is that we may ALL produce builds for any of the projects, making the onramp for new developers less steep, while still maintaining an exceptionally high level of quality.
 
-Further, the projects should adhere to the principles of 'architecture as code' - and should require a very minimal set of dependencies in order to contribute. That said, we have chose to center around docker for creating builds. Windows builds may be created using `wine`. If Wine is not an option, the standard may be broken to accomodate such cases.
+The projects should follow the 'architecture as code' principal - and should require a very minimal set of dependencies. 
 
 It is the responsibilty of the build tooling to write artifacts to the appropriate location as outlined in this specification.
 
 ## Build Folder Name
+
 The cannonical folder for builds SHALL be named `build` and be located at the root of the project repository.
 Each project MUST `git ignore` the `build` folder.
 
 ## Build Folder Structure
+
 Files and folder names MUST be lowercase.
 The result of the build process should create a folder structure as follows:
+
 ```
 .
 └── build
-    └── {platform}
+    └── {target}
         └── {project-name}.{ext}
 ```
 
@@ -46,25 +50,45 @@ Below is an example:
         └── my-build.exe
 ```
 
-## Build Platform Targets
-Below is a list of platforms we will target for each project
+## Build Targets
+
+Below is a list of suggested targets for a project
 1. windows
 2. linux
-3. mac
+3. macos
+
+## Build script
 
-## Docker-compose to create a build
-Each project MUST have a /docker-compose.build.yml file.
-The result of this is that every project MUST produce a build for each target platform when the following command is invoked:
- - `docker-compose up -f ./docker-compose.build.yml`
+Each release target MUST have a `bin/build.{target}.{ext}` file.
 
-The docker-compose.build.yml file MUST be placed in the project's root directory.
-Any dockerfiles used by the docker-compose may be placed at the discretion of the developer of the project.
+The result of this is that every project MUST produce a build for each target when the following command is invoked:
+
+```
+bin/build.{target}.{ext}`
+```
+
+The file MUST be placed in the project's `bin` directory.
 
 ## Build Pipeline
-Starting from clean master branch with latest HEAD
 
-### Building all targets
-`docker-compose -f ./docker-compose.build.yml up` should create builds for each of the targeted platforms, and place the build artifacts in a folder structure outlined above.
+### Building targets
+
+`bin/build.{target}.{ext}` should create builds for each of the targets, and place the build artifacts in a folder structure outlined above.
 
-### Building specific target
-`docker-compose -f ./docker-compose.build.yml up [windows | linux | mac]`
+### Windows
+
+```
+bin/build.windows.bat
+```
+
+### Linux
+
+```
+bin/build.linux.sh
+```
+
+### Macos
+
+```
+bin/build.macos.sh
+```

CONTRIBUTING.md

@@ -40,31 +40,22 @@ For small documentation changes and fixes, these can be done quickly following t
 ### Submitting changes
 
 1. Review & Test changes
-
-If the code changed, then test it. If documentation changed, then preview the rendered Markdown.
-
+    * If the code changed, then test it. If documentation changed, then preview the rendered Markdown.
 2. Commiting
-
-Follow the [Convention Commits](CONVENTIONAL_COMMITS.md) guidelines to create a commit message
-
- 
+    * Follow the [Convention Commits](CONVENTIONAL_COMMITS.md) guidelines to create a commit message
 3. Sign the CLA
- 
-Make sure you've signed the repository's Contributor License Agreement. We are not asking you to assign copyright to us, but to give us the right to distribute your code without restriction. We ask this of all contributors in order to assure our users of the origin and continuing existence of the code. You only need to sign the CLA once.
- 
- 
+    * Make sure you've signed the repository's Contributor License Agreement. We are not asking you to assign copyright to us, but to give us the right to distribute your code without restriction. We ask this of all contributors in order to assure our users of the origin and continuing existence of the code. You only need to sign the CLA once.
 4. Submit a pull request
-
-Push local changes to your 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 your 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
 
-Follow the build process is outlined in [the BUILDING spec](BUILDING.md) to create a build.
+Follow the build process is outlined in [BUILDING.md](BUILDING.md) to create a build.
 
 
 ## Releasing
 
-Follow the release process is outlined in [the RELEASING spec](RELEASING.md) to create a release.
+Follow the release process is outlined in [RELEASING.md](RELEASING.md) to create a release.
 
 

README.md

@@ -1,12 +1,14 @@
 # Pristine
 
-Pristine is an open source repository in its original condition. Its goal is to be a starting point for new open source projects following a Documentation Driven Development pattern, as well as a resource from which to augment existing documentation.
+Pristine is an open source repository in its original condition.
+
+There are a lack of repositories to start from to build community driven open source projects. Pristine is a starting point, it follows a Documentation Driven Development approach, and can be used as a resource to augment existing documentation.
 
 ## Documentation Driven Development
 
-There are many ways to drive open source development. Organizing solutions to this challenge around the README gives a middle ground between technical and non-technical specifications.
+There are many ways to drive open source development. Documenting the problem in the README gives a middle ground between technical and non-technical specifications. This allows organizing solutions to this challenge around community and documentation.
 
-> 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.
+> [...] 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
 
@@ -38,14 +40,5 @@ To get started, [fork](https://help.github.com/articles/fork-a-repo/) or [duplic
 
 ### Contributing
 
-How to contribute, build and release are outlined in [CONTRIBUTING.md](CONTRIBUTING.md), [BUILDING.md](BUILDING.md) and [RELEASING.md](RELEASING.md) respectively.
-
-### Requirements
-
-#### Docker:
-
-Docker is used as a building block in [BUILDING.md](BUILDING.md) and [RELEASING.md](RELEASING.md). 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/)
+How to contribute, build and release are outlined in [CONTRIBUTING.md](CONTRIBUTING.md), [BUILDING.md](BUILDING.md) and [RELEASING.md](RELEASING.md) respectively. Commits in this repository follow the [CONVENTIONAL_COMMITS.md](CONVENTIONAL_COMMITS.md) specification.
 

RELEASING.md

@@ -1,4 +1,4 @@
-# Project Releasing
+# Releasing
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here.
 
@@ -16,54 +16,50 @@ We propose:
 
 It is NOT the purpose of this document to describe how a project might create a build, NOR is it describing a strcture in which projects MUST write build artifacts to. It is describing the structure of the releases themselves.
 
-## Release Targets
-1. Github
-2. (tentative) docker
-
 ## Release Pipeline
-The only parameter to the release pipeline is the new semver to use. We will refer to it as newVer.
-Starting from a clean branch:
 
 ### Create a build from current branch
-Process is outlined in [the BUILDING spec](building.md)
-in summary, we will simply:
+
+Process is outlined in [BUILDING.md](BUILDING.md)
+
 1. Clean the build directory
-2. run: `docker-compose up -f ./docker-compose.build.yml`
+2. run: `bin/build.{target}.{ext}`
 
-### Sign the releases.
- - MUST be a pgp signature
- - MUST be the same pgp key as is registered with Github
- - MUST be a detached ascii-armored (.asc) signature 
- - All files in the build folder MUST have an associated signature file
+### Bump the version of the project
+
+Projects SHOULD automated the version bump following [CONVENTIONAL_COMMITS.md](CONVENTIONAL_COMMITS.md).
 
 ### Generate Changelog
-For our projects we will be using [conventional changelog](https://github.com/conventional-changelog/conventional-changelog).
 
-1. Generate the changelog. EX: `conventional-changelog -p angular -i CHANGELOG.md -s -r 0`
-2. git add the changelog diff: `git add CHANGELOG.md`
+Projects SHOULD use generated changelogs from following [CONVENTIONAL_COMMITS.md](CONVENTIONAL_COMMITS.md).
 
-### Bump the version of the project
-This is project specific.
+### Commit the bump + changelog update
 
-use the convention outlined by [VERSIONING.md](VERSIONING.md):
- - `bin/bump-version.sh {newVer}`
+A project MUST generate a commit with the changes.
 
-### Commit the bump + changelog update
-generate a commit with the changes.
+### Tag the commit with the bumped version
+
+A project MUST be tagged with the semantic versioning scheme from [VERSIONING.md](VERSIONING.md).
+
+### Sign the releases.
+
+ - MUST be a pgp signature
+ - MUST be the same pgp key as is registered with Github
+ - MUST be a detached ascii-armored (.asc) signature 
+ - All files in the build folder MUST have an associated signature file
 
 ### Push changelog & version bump
-simple as `git push`.
 
 ### Run Release Targets
+
 For each of the desired release targets, prepare and push the release.
 
-#### Github Release
-Using [Github release tool](https://github.com/c4milo/github-release), push a release with the following fields:
+#### Example Release Targets
+
+1. Github
+2. Docker Hub
 
+## Resources
 
-| Field name       | Content                                                        |
-| ---------------- | -------------------------------------------------------------- |
-| tag version      | {newVer}                                                       |
-| title            | same as tag                                                    |
-| description      | {changelog for specific version}                               |
-| release binaries | for each platform: `{project-name}-{platform}-{version}.{ext}` |
+- [semantic-release](https://github.com/semantic-release/semantic-release)
+- [Conventional Commits](https://conventionalcommits.org/

VERSIONING.md

@@ -12,7 +12,7 @@ It also describes standardized tooling around manipulating the version
 ## Semver
 A project MUST use Semantic Versioning [semver](https://semver.org). Build metadata MAY NOT be used in a project. Build metadata SHOULD be ignored.
 
-A Basic summary of Semantic Versioning taken from: [semver.org(https://semver.org)
+A Basic summary of Semantic Versioning taken from: [semver.org](https://semver.org)
 
 ### Summary:
 
@@ -22,7 +22,3 @@ MAJOR version when you make incompatible API changes,
 MINOR version when you add functionality in a backwards-compatible manner, and
 PATCH version when you make backwards-compatible bug fixes.
 Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
-
-## Standardized tooling
-
-each project should implement `bin/bump-version.sh {newVer}`