etclabscore / pristine

Pristine is an open source repository in its original condition.

Pristine

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.

How to use Pristine in your project

There are 2 options for using pristine with your project.

1. Fork this repo as the start of your own, OR
2. follow these instructions to use it on an existing repository.

Documentation Driven Development

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.

[...] 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 by Tom Preson-Werner

Conventions and Specifications

Using conventions, documentation and specifications make it easier to:

• communicate the problem you are solving
• ease onboarding
• build and use composable tools
• promote open source contribution and engagement
• promote issue and feature discussion on Github itself

Resources

• opensource.guide
• Github community profiles for public repositories
• Readme Driven Development
• pengwynn/flint
• Working Backwards
• Literate programming
• Hammock Driven Development
• Inversion and The Power of Avoiding Stupidity
• choosealicense.com
• The Documentation Compendium

Getting Started

To get started, fork or duplicate the repository. Then edit this file and delete everything above this line.

---

Contributing

How to contribute, build and release are outlined in CONTRIBUTING.md, BUILDING.md and RELEASING.md respectively. Commits in this repository follow the CONVENTIONAL_COMMITS.md specification.

pristine's Issues

Issue templates

https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/

automate label for `too fresh` or extra labels

Include instructions for installing to an existing repo

I've accomplished the process over at open-rpc/spec#12

I used the process outline here:

https://thoughts.t37.net/merging-2-different-git-repositories-without-losing-your-history-de7a06bba804

Remove Jenkinsfile

Is your feature request related to a problem? Please describe.
Not all projects use Jenkinsfile's

Describe the solution you'd like
Let's just remove it

Describe alternatives you've considered
We looked at circleci/travis/jenkins and there isnt a good alternative right now

Conventional commits

Is your feature request related to a problem? Please describe.

Currently conventional commits refers and adheres to http://conventionalcommits.org/.

My issue is that this "Conventional commits" style isn't really conventional; it's actually pretty opinionated.

Since the Conventional Commits spec allows arbitrary xxx[yyy]:, it seems like the only thing that structuring a message in this way does is enable easier machine readability¹ (and not work directly to Documentation Driven Development in the sense of legible and accurate documentation around development). It's just a punctuation spec, not a content spec, and despite it's name is not very generalized.

Describe the solution you'd like

Something as generic as possible, while still being able to describe something that's actually useful.

In my opinion there are more useful resources we can draw from for outlining a rubric for a "good" commit message, for example

• https://secure.phabricator.com/book/phabflavor/article/writing_reviewable_code/.
• https://github.com/torvalds/subsurface-for-dirk/blob/a48494d2fbed58c751e9b7e8fbff88582f9b2d02/README#L88

Describe alternatives you've considered

• scope: message; useful for big repos, not so much for small ones
• Commit messages should start with a capital letter
• problem: xxx / solution: yyy structure
• https://rfc.zeromq.org/spec:44/C4/

Resources

I spent 10 minutes looking through "top starred" repos on Github for examples (for lack of a better "canon of the conventional").

A list of example repos that don't follow this pattern:

• https://github.com/golang/go/commits/master - Note here that cmd/api: fix no go files package panic is used, where cmd/api: is the package containing the changes. In fact, this kind-of-almost fits the Conventional Commit style, except that "scope" (optional) is used in place of "type" (mandatory).
• https://github.com/torvalds/linux/commits/master
• https://github.com/python/cpython/commits/master
• https://github.com/php/php-src/commits/master
• https://github.com/git/git/commits/master
• https://github.com/netdata/netdata/commits/master
• https://github.com/openssl/openssl/commits/master
• https://github.com/ethereum/go-ethereum/commits/master
• https://github.com/pomber/git-history/commits/master
• https://github.com/30-seconds/30-seconds-of-code/commits/master
• https://github.com/toddmotto/public-apis/commits/master
• https://github.com/transloadit/uppy/commits/master
• https://github.com/facebook/react/commits/master
• https://github.com/trekhleb/javascript-algorithms/commits/master
• https://github.com/axios/axios/commits/master
• The default style generated by Github for suggestioned commits or when using their browser editor, like:
  

Repos I found that do use it:

• https://github.com/vuejs/vue/commits/dev
• ... and from their docs, a list of some more repos that do use it, all of which are Javascript projects

---

1. From the docs, 3/5 of "Why Use Conventional Commits" are for computer automation.

changelogs?

re: https://github.com/etclabscore/pristine/blob/master/RELEASING.md#generate-changelog

Don’t let your friends dump git logs into changelogs.
https://keepachangelog.com/en/1.0.0/

This is just a devil's advocate note. Personally I'd be pretty inclined to use programmatic means to handle what I would consider to be a chore of handling changelog maintenance.

With that said... Do we really need changelogs as a standard-across-the-board artifact? For me, to answer questions around what has been happening on the development of projects I typically use a combination of git logs, release notes, the github issue tracker, and, if necessary, an internet search engine. I don't know if a changelog has ever held my attention for more than 4 seconds.

Use either ubiquitous tools or official docker images

Tooling MUST have associated docker images, and those should be used in the docker compose commands.

Just jotting this idea from dev discussion...

Add 'pristine' topic

Create badges defaults

In the readme we should have something like 'powered by pristine' or something.

Also, having the common badges would be great.

note on reviewable commits

https://secure.phabricator.com/book/phabflavor/article/writing_reviewable_code/

maybe we want to think about linking or adding some content here
https://github.com/etclabscore/jade/blob/master/CONVENTIONAL_COMMITS.md

Readme is unclear as to what this project is

Describe the bug
Without talking to a contributor it is unclear what the purpose of pristine is. I would suggest updating the readme to focus on how to use pristine.

add SUPPORT.md to add instructions on getting support

You can add a SUPPORT.md file to your repository's root and when someone creates an issue in your repository, they will see a link to your project's SUPPORT file.

https://help.github.com/articles/adding-support-resources-to-your-project/

Release pipeline seems out of order... ?

https://github.com/etclabscore/pristine/blob/master/RELEASING.md#release-pipeline

The current process is:

1. Build
2. Sign
3. Changelog
4. Version bump
5. Commit
6. Push
7. Draft release for targets (eg Github Releases)

Problems:

• (1) Sign should come after (4) Version bumping. For programs that are version-aware (eg. multigeth) doing otherwise will yield releases w/ "dirty" versions.
• (4) Version bump should come after (5) Commit. Otherwise tagged releases will not include the changelog changes.

Proposed solve:

1. Changelog
2. Commit
3. Version bump
4. Build
5. Sign
6. Push
7. Draft

Rel #11

Labeling scheme?

Should we consider offering a standard scheme beyond the default for Github labels?

Here are a few interesting ones I've found:

• https://github.com/paritytech/parity-ethereum/labels?page=1&sort=name-asc
• https://github.com/neovim/neovim/labels
• https://github.com/torvalds/linux/labels

Resources:

• https://robinpowered.com/blog/best-practice-system-for-organizing-and-tagging-github-issues/

Could be managed with something like this tool: https://github.com/jvandemo/copy-github-labels-cli

add note about pristine-cli in readme

https://github.com/etclabscore/pristine-cli#how-to-use-pristine-cli

Make headings through out docs linkable

example:

##### <a name="documentationChanges"></a> Documentation Changes

loosen BUILDING and RELEASING requirements

Describe the bug
Currently we only loosely follow BUILDING.md and RELEASING.md

Expected behavior
We should match what we do in most of our repos, specifically the pristine-x built on top of this one

Additional context
example: node repos use npm build
example: some repos use publish.sh

Automated Testing & Deploying

Given the specs outlined in this repository, we should have tools to boot a ci/cd local or remote environment.

• get working locally (and on other peoples machines)
• get running on AWS
• get accounts for jenkins
• set up a github integration for pristine
• add TESTING.md to describe how to test projects

add mdv to validate markdown links

Is your feature request related to a problem? Please describe.
I'm always frustrated when markdown links are broken. They are a big part of markdown and specs.

Describe the solution you'd like
Add mermade/mdv to Jenkinsfile as a step/stage test to validate markdown links on pull requests.

Additional context
see also open-rpc/spec#74

Implementation of the USB 3.0 controller not found!

Installing from OSX mojave. All deps installed via brew cask

Pristine repository [use the contents of this issue to create new issues on other repos]

Describe the feature you would like
This repo should be using pristine to get a license, better baseline documentation, and encourage contributions.

Describe the solution
https://github.com/etclabscore/pristine#how-to-use-pristine-in-your-project

pull request bot

if you've forked from or are a pristined project we can track it and make a pull request back when pristine base repository changes.

we can poll for either certain commits, or all commits from etclabscore/pristine in an orgs repos, and then if pristine changes, make a PR back with the changes.

bin/bump-version.sh missing

Cited here

pristine/VERSIONING.md

Line 28 in f06cafd

each project should implement `bin/bump-version.sh {newVer}`

and here

pristine/RELEASING.md

Line 49 in ffe5775

- `bin/bump-version.sh {newVer}`

.

Here's an over-the-top solution: https://github.com/truelab/git-bump-sh/blob/master/bin/bump
Here's a lighter-weight solution: https://gist.github.com/petervanderdoes/2877083

If we're managing version bumps programmatically, what should the tag messages be?

create pristine-jade-app with appbar

Having a pristine project set up with the material ui + app bar + theming gets us pretty far in starting new tools. We should have t his as a pristine-x repo to start from.