github.com/blend/go-sdk@v1.20240719.1/README.md (about)

     1  go-sdk
     2  ======
     3  
     4  [![Build Status](https://circleci.com/gh/blend/go-sdk.svg?style=shield)](https://circleci.com/gh/blend/go-sdk)
     5  [![GoDoc](https://godoc.org/github.com/blend/go-sdk?status.svg)](https://godoc.org/github.com/blend/go-sdk)
     6  
     7  `go-sdk` is our core library of packages. These packages can be composed to create anything from CLIs to fully featured web apps.
     8  
     9  The general philosophy is to provide loosely coupled libraries that can be composed as a suite of tools, vs. a `do it all` framework.
    10  
    11  # Requirements
    12  
    13  This repository requires golang version 1.16+ to be installed.
    14  
    15  To run tests, it is required that you have Docker installed, with docker-compose, or have postgres running locally.
    16  
    17  # Addtional CLI Tools
    18  
    19  We also provide the following CLI tools to help with development that leverage some of these packages:
    20  
    21  - `cmd/ask` : securely input secrets and output to a file to be read by templates.
    22  - `cmd/copyright` : injects and verifies copyright headers are present in files.
    23  - `cmd/cover` : allows for project level coverage reporting and enforcement.
    24  - `cmd/job` : run a command on a cron schedule; useful for writing jobs as kubernetes pods.
    25  - `cmd/profanity` : profanity rules checking (i.e. fail on grep match).
    26  - `cmd/recover` : recover crashed processes (to be used when debugging panics).
    27  - `cmd/semver` : semver manipulation and validation.
    28  - `cmd/shamir` : securely partition secrets using shamir's sharing scheme.
    29  - `cmd/template` : commandline template generation using golang `text/template`.
    30  
    31  # Repository Organization Notes
    32  
    33  - The repository is organized into composible packages. They are designed to be as loosely coupled as possible, but are all in a single repo to facilitate breaking change management.
    34  - Any commandline programs should live under `cmd/**` with the core library code in a top level package. The CLI should just be the bare minimum to run the library from the cli.
    35  
    36  # Contributing
    37  
    38  We currently don't accept PRs as this repository at this time, but feel free to log issues and we'll address when we can.
    39  
    40  # Code Style Notes
    41  
    42  ## The "Options" Pattern
    43  
    44  - The "Options" pattern is a variadic set of arguments as functions that mutate the returned object, typically in the constructor.
    45  	- This lets callers add their own mutators to be used in constructors.
    46  	- It also lets callers establish a set of "default" options that can be combined / overridden later.
    47  	- It also reduces the amount of code required in the `go-sdk` repo itself.
    48  
    49  ## Other General Notes
    50  
    51  - Where possible, follow the [golang proverbs](https://go-proverbs.github.io/).
    52  - Make the zero value useful. Some situations require pointers, and are noted exceptions.
    53  - Export all fields unless strictly internal state and would *never* be set by calling code.
    54  - Where possible, packages should export configuration objects that can be used to create the core types of that package. Those configuration objects should be readable from both JSON and YAML.
    55  - Anything that can return an error, should. Anything that needs to return a single value (but would return an error) should panic on that error and should be prefixed by `Must...`.
    56  - Minimize dependencies between packages as much as possible; add external dependencies with *extreme* care.
    57  	- Notable exceptions include:
    58  		- airbrake
    59  		- sentry
    60  		- lib/pq
    61  		- aws sdk
    62  		- datadog
    63  
    64  # Version Management
    65  
    66  We follow calendar versioning. What that means in practice:
    67  
    68  > [major].[year][month][day].[patch]
    69  
    70  Major version changes are changes that break backwards-compatibility. A breaking change is defined as a change that would cause code written against the current major version having a build failure of any type. That's even for a trivial find and replace. Once you merge a new api or name for an object after CR, that's it. Major changes are rolled up into a release, at most, once-per-year.
    71  
    72  Minor version changes are additions to exported types, values, or functions that don't cause break backwards compatibility. These types of changes are rolled into a new minor version at an approximate monthly cadence.
    73  
    74  Patch versions is the used to distinguish different versions from the same calendar day.
    75  
    76  The current version is stored in the `VERSION` file at the root of the package.
    77  
    78  Currently we support 1 major version branches of the go-sdk.
    79  
    80  - v1.xxxxxxxx.x
    81  
    82  All other major versions are deprecated. The previous semver scheme is deprecated.
    83  
    84  
    85  ## Version Release Cycle
    86  
    87  We will not be releasing more than 1 major version in any calendar year, and major versions will recieve at least 2 years of support before being deprecated.
    88  
    89  # Bugs and Feature Requests
    90  
    91  Please use the [issues page](https://github.com/blend/go-sdk/issues) to report any bugs or request new features be added to the SDK. We welcome contributions to any issue reported therein, including those you report. Please ping us on the issue itself for things like access requests.
    92  
    93  # Maintainers
    94  
    95  This repo is maintained by a core group of [Blend](https://github.com/blend) employees, including:
    96  - [Addie Bendory](https://github.com/addie)
    97  - [Alex Kaplan](https://github.com/KaplanAlex)
    98  - [Chinmaya Sharma](https://github.com/chinmayasharma)
    99  - [Igor Morozov](https://github.com/igmor)
   100  - [Justin Fan](https://github.com/Justinfan827)
   101  - [Kevin Wang](https://github.com/xorkevin)
   102  - [Michael Turner](https://github.com/mat285)
   103  
   104