Make Yer Contributions!

It’s always good to get stuck in and help wherever you can, and we here at The Bearmint Mining Company pride ourselves on our ability to collaborate with folks from all over! Now not just anyone can contribute of course - there are a couple of requirements we have for the purposes of quality and all that, so not every Tom, Dick and Harry can just mosey on in and start throwin’ pull requests at us like it’s an afternoon free-for-all at the local saloon!

And of course we have our processes that need to be followed. We obviously respect that developers have their own way of gettin’ things done, but without some kind of protocol, well, our codebase’ll be a right mess faster than you can say jumpin’ Jehoshaphat! We just can’t have that partners! We have a lot of people what rely on us fer their financial security and peace of mind, so we can’t be all willy-nilly about how we conduct our business! It’s reprehensible in the extreme to just allow anyone to do as they please, so in order to circumvent a rapid descent into the realms of chaos and madness, we humbly ask that you abide by our rules and remain cordial at all times.

Yep, Buckley is rough and tough to be sure, but he’s also kind, partners. And we in the Bearmint Gang also value and uphold kindness and mutual respect at all times. If we want to grow and evolve as an organization, we need to be civilized and as diplomatic and inclusive as possible. Fer that reason any discussions that take place need to be kept friendly and professional on an ongoin’ basis. Any self-respectin’ cowpoke don’t need to be told that, but just in case you were thinkin’ of gettin’ up to some hijinks, well, you’ve been duly warned!

So you might be askin’ what our procedures are, and we’re more than happy to share ‘em with you. Take some time to familiarize yerself with everythin’, and if you have any questions, we’re more than happy to answer them fer you!

Requests For Comments (RFCs)

A Request for Comments (RFC) serves as a record of discussion on an open-ended topic related to the design and implementation of Bearmint that doesn’t require immediate attention or a decision to be made.

An RFC is thus a historical record of a high-level discussion that may otherwise only exist in an ad hoc way (for example, via gists or Google Docs), making access difficult or even impossible for any interested parties after the fact. An RFC may give rise to more specific architectural decisions for Bearmint, but all records of these decisions must appear separately under Architecture Decision Records (ADRs) - we’ll discuss these more in just a moment.

As a general rule of thumb, if you can articulate a specific question that requires an answer, write an ADR. However, If you need to explore the topic and gather input from others to determine what questions need to be answered, an RFC is more appropriate.

RFC Content

An RFC should provide:

  • A changelog, documenting when and how the RFC has changed
  • An abstract, briefly summarizing the topic so the reader can quickly determine whether it’s relevant to their area of interest or not
  • Any background information a reader may need to understand and participate in the substance of the discussion (you may include links to other documents here), and
  • The discussion itself, which constitutes the primary content of the document

Architecture Decision Records (ADRs)

Architecture Decision Records (ADRs) provide a complete history of all decisions, modifications, proposals and architecturally-relevant undertakings for a given software project. Since ADRs lack specificity in terms of exactly which piece of software is receiving proposals and modifications, we at Bearmint refer to ADRs as Bearmint Enhancement Proposals (BEPs) as this designation relates directly to Bearmint and all decisions concerning the project.

BEPs adhere stringently to the conventions of ADRs but differ in that they tend to de-emphasize technical jargon and complexity in favor of comprehension, education and relatability.

To this end, several different types of BEPs exist as certain proposals will affect specific parts of Bearmint's architecture. At present, the following types apply:

Standards - This encompasses changes to the network protocol, block or transaction validation, or any elements that may have a direct effect on interoperability Informational - This includes any design issues and/or general guidelines - note that this type of BEP does not exist for the purpose of proposing new features and does not represent community consensus Process - This type of BEP describes or proposes a change in the way certain components work together or how a given process occurs. While these overlap with Standards, they apply outside of Bearmint's core protocol

It is also important to note that BEPs apply to both technical and non-technical changes. In essence, anything that has a measurable effect on the way Bearmint functions or new features become part of its end-user offering may become a BEP.

The following information provides further clarity on the nature of Architectural Decisions (ADs) as well as several other concepts that relate directly to architecture as a whole:

  • An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant
  • An Architecturally Significant Requirement (ASR) is a requirement with a measurable effect on both a software system’s architecture and quality
  • An Architectural Decision Record (ADR) captures a single AD which is akin to writing personal notes or meeting minutes. As a result, all ADRs created and maintained within a project constitute its decision log
  • All of the above falls within the realm of Architectural Knowledge Management (AKM)
  • You can learn more about the concept of ADRs in this blog post.

Rationale

ADRs serve as the primary mechanism for proposing new features, designs and processes as well as collecting community inputs on an issue. It also documents any and all design decisions within a given project. As such, an ADR should provide:

  • Context on the relevant goals and current state of the project
  • Proposed changes to achieve the goals of the project
  • A summary of the pros and cons of a decision
  • References, and
  • A Changelog
  • Note the distinction between an ADR and a spec. An ADR provides the context, motivation, reasoning, and justification for a change in architecture (or for the architecture of something new). In contrast, a spec is a significantly more succinct and streamlined summary of the current state of a project.

Ready to Get Yer Hands Dirty?

You should now have a better understandin’ about how we handle contributions here at Bearmint. That said, we’re always happy to hear from folks who are fans of our work. If you’re unsure of how to contribute or have somethin’ else to offer, we’d be more than happy to hear from you. We love workin’ with our community to hear their suggestions and find out exactly what it is they have in mind. And who knows? Maybe yer idea is exactly what we’re lookin’ fer, so drop us a line!

In future blog posts we’ll provide you with more insights and guides on how to do a bunch of cool stuff with Bearmint, so keep your eyes peeled and keep following us as we gear up for our official release!