Merge pull request #318 from dvonthenen/project-contribution-docs

Defining the Contribution Process and Project Management Process

.github/BRANCH_AND_RELEASE_PROCESS.md

@@ -0,0 +1,88 @@
+# Branch and Release Process
+
+- [Branch and Release Process](#branch-and-release-process)
+  - [Branching Process](#branching-process)
+    - [Branching Methods](#branching-methods)
+    - [Branch Process for This Project](#branch-process-for-this-project)
+      - [Why Pick This Strategy?](#why-pick-this-strategy)
+  - [Release Process](#release-process)
+
+## Branching Process
+
+In software development, selecting an appropriate Git branch strategy is crucial for maintaining code integrity, fostering collaboration, and streamlining project management. A well-defined branch strategy helps teams manage code changes systematically, reducing the risk of conflicts and ensuring that features, bug fixes, and releases are properly isolated.
+
+## Branching Methods
+
+For open-source projects, three popular Git branching strategies are:
+
+1. **Git Flow**:
+
+   Git Flow is a robust branching strategy that uses multiple branches for feature development, releases, and hotfixes. The primary branches include:
+
+   - `main`: Holds the production-ready code.
+   - `develop`: Integrates all completed features and serves as the staging area for the next release.
+   - `feature/*`: Branches off from `develop` for new features.
+   - `release/*`: Branches off from `develop` when preparing a new release.
+   - `hotfix/*`: Branches off from `main` for critical fixes that need to be deployed immediately.
+
+   Git Flow is suitable for projects with regular release cycles and helps maintain a clear and structured workflow.
+
+2. **GitHub Flow**:
+
+   GitHub Flow is a simpler, more streamlined approach ideal for projects that deploy frequently. Its key principles include:
+
+   - A single `main` branch always containing deployable code.
+   - Branches for each feature or bug fix that branch off from `main` and merge back into `main` upon completion.
+   - Continuous deployment from the `main` branch, allowing for fast iterations and rapid delivery of new features.
+
+   This strategy emphasizes simplicity and continuous integration, making it well-suited for fast-paced development environments.
+
+3. **Trunk-Based Development**:
+
+   Trunk-Based Development focuses on keeping a single, stable branch (the "trunk") where all developers commit their code. Key practices include:
+
+   - Small, frequent commits directly to the `main` branch.
+   - Short-lived feature branches that are quickly merged back into `main`.
+   - Emphasis on automated testing and continuous integration to ensure code stability.
+   This strategy aims to minimize merge conflicts and maintain a high level of code quality, promoting rapid feedback and collaboration.
+
+Each of these strategies has its own strengths and is chosen based on the specific needs and workflow of the project.
+
+## Branch Process for This Project
+
+This project's branch process sits between **GitHub Flow** and **Git Flow** by taking the best of both worlds. This projects branching strategy looks like:
+
+Aspects used from **GitHub Flow**:
+
+- A single `main` branch always containing deployable code.
+- Branches for each feature or bug fix that branch off from `main` and merge back into `main` upon completion.
+- Continuous deployment from the `main` branch, allowing for fast iterations and rapid delivery of new features.
+
+Aspects used from **Git Flow**:
+
+- `release-v[0-9]+/*`: Branches off from `main` when preparing a new release.
+- `hotfix/*`: Branches off from `main` (or a release branch) for critical fixes that need to be deployed immediately.
+
+### Why Pick This Strategy?
+
+This is done in order to foster:
+
+- maximum collaboration with external contributors
+  - since we are on GitHub, it's the standard workflow by default. (its why `develop`, or `alpha`/`beta`/etc branches aren't created by default)
+  - it's intuitively obvious where contributions (ie PRs) need to merge with zero background on the project
+  - this puts all bespoke, project, and repo management on the project maintainers
+- forces the project maintainers to embrace CI/CD
+  - `main` must work at all times; therefore, main can be deployed or released at all times
+- things don't always go according to plan
+  - having the branching strategy for releases **Git Flow** helps support of concurrent versions
+  - provides flexibilty to create release trains
+
+## Release Process
+
+The release process for this project is designed to balance the rapid iteration capabilities of **GitHub Flow** with the structured release management of **Git Flow**. Releases are typically created off `main` since we strive to keep backwards compatibility and prevent breaking any interfaces. This implies that releases are basically a single train pushing features out. In terms of new feature release health, you should consider the `main` branch unstable. Consumers of this SDK should **ONLY** ever consume a tagged release on the repo release page.
+
+In the event of a breaking interface change, a `release-v[0-9]+` branch is created off the main branch or at the point of divergence. Additionally, according to semver best practices, the project is accompanied by a major version bump. It's implied that these different interfaces are to be supported until determined by the company SLA.
+
+In scenarios where urgent issues arise, the `hotfix` branch comes into play. A hotfix branch is created off main or the relevant release branch to address critical issues that need immediate attention. After the hotfix is implemented and thoroughly tested, it is merged back into both the `main` and the `release-v[0-9]+` branches to ensure the fix is included in the current and future versions of the project.
+
+This dual approach of leveraging both **GitHub Flow** and **Git Flow** ensures that the project can iterate quickly while maintaining high standards of code stability and release management.

.github/CODE_CONTRIBUTIONS_GUIDE.md

@@ -0,0 +1,190 @@
+# Development Guide
+
+- [Development Guide](#development-guide)
+  - [Welcome](#welcome)
+  - [Preparing Your Local Operating System](#preparing-your-local-operating-system)
+    - [Setting Up macOS](#setting-up-macos)
+    - [Setting Up Windows](#optional-setting-up-windows)
+  - [Installing Required Software](#installing-required-software)
+    - [Installing on Windows](#installing-on-windows)
+    - [Installing on macOS](#installing-on-macos)
+    - [Installing on Linux](#installing-on-linux)
+  - [Installing Docker](#installing-docker)
+  - [GitHub Workflow](#github-workflow)
+
+## Welcome
+
+This document is the canonical source of truth for building and contributing to the [.NET SDK][project].
+
+Please submit an [issue] on GitHub if you:
+
+- Notice a requirement that this doc does not capture.
+- Find a different doc that specifies requirements (the doc should instead link here).
+
+## Preparing Your Local Operating System
+
+Where needed, each piece of required software will have separate instructions for Linux, Windows, or macOS.
+
+### Setting Up macOS
+
+Parts of this project assume you are using GNU command line tools; you will need to install those tools on your system. [Follow these directions to install the tools](https://ryanparman.com/posts/2019/using-gnu-command-line-tools-in-macos-instead-of-freebsd-tools/).
+
+In particular, this command installs the necessary packages:
+
+```bash
+brew install coreutils ed findutils gawk gnu-sed gnu-tar grep make jq
+```
+
+You will want to include this block or something similar at the end of your `.bashrc` or shell init script:
+
+```bash
+GNUBINS="$(find `brew --prefix`/opt -type d -follow -name gnubin -print)"
+
+for bindir in ${GNUBINS[@]}
+do
+  export PATH=$bindir:$PATH
+done
+
+export PATH
+```
+
+This ensures that the GNU tools are found first in your path. Note that shell init scripts work a little differently for macOS. [This article can help you figure out what changes to make.](https://scriptingosx.com/2017/04/about-bash_profile-and-bashrc-on-macos/)
+
+### (Optional) Setting Up Windows
+
+If you are running Windows, you can contribute to the SDK without requiring Linux-based components like a terminal/shell. Is this step essential? No. Will this help out some time down the road? Yes!
+
+- If you're using Windows 10, Version 2004, Build 19041 or higher, you can use Windows Subsystem for Linux (WSL) to perform various tasks. [Follow these instructions to install WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
+
+## Installing Required Software
+
+After setting up your operating system, you will be required to install software dependencies required to run examples, perform static checks, linters, execute tests, etc.
+
+We will attempt to provide bootstrapping instructions for various operating systems and development environments; however, we cannot document them all. Therefore, we will select a few common combinations and provide support for them.
+
+### Installing on Windows
+
+It is **HIGHLY** recommended that if you are running windows, that you use [Visual Studio](https://visualstudio.microsoft.com/) (and not [Visual Studio Code](https://code.visualstudio.com/)). This project takes advantage of numerous features only available on Visual Studio.
+
+Setting up the environment with Visual Studio is as easy as installing Visual Studio, opening the [Deepgram.Dev.sln](https://github.com/deepgram/deepgram-dotnet-sdk/blob/main/Deepgram.Dev.sln) solution file and attempting to build all the components. Visual Studio will prompt for any missing dependencies required, download them for you, and take care of any installation required.
+
+This is literally the "easy button" option.
+
+#### (Alterative) Visual Studio Code
+
+If Visual Studio is not an option, cost being a very valid example, an alterative is to use [Visual Studio Code](https://code.visualstudio.com/).
+
+1. You can download and install Visual Studio Code here: [https://code.visualstudio.com/Download](https://code.visualstudio.com/Download).
+
+1. Download and install the latest .NET SDK and Run-time, which can be found at [https://dotnet.microsoft.com/en-us/download/dotnet/8.0](https://dotnet.microsoft.com/en-us/download/dotnet/8.0).
+
+1. To configure Visual Studio Code to work with C#, download and install [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) from Microsoft.
+
+**NOTE:** By default, we target the oldest supported .NET in the projects contained within this repo. This is done to ensure we aren't using functionality that is supported at a later version and onward. Using later versions of the .NET SDK is friendlier when it comes to installation. If you use .NET 8, don't forget to update the individual projects to use .NET 8.
+
+### Installing on macOS
+
+### Xcode
+
+Some build tools were installed when you prepared your system with the GNU command line tools earlier. However, you will also need to install the [Command Line Tools for Xcode](https://developer.apple.com/library/archive/technotes/tn2339/_index.html).
+
+#### Running and Developing .NET on macOS
+
+For macOS, there are two options. The recommended option is [Visual Studio Code](https://code.visualstudio.com/) and the alternative is [Rider by JetBrains](https://www.jetbrains.com/rider/)
+
+#### Visual Studio Code
+
+1. You can download and install Visual Studio Code here: [https://code.visualstudio.com/Download](https://code.visualstudio.com/Download).
+
+1. Download and install the latest .NET SDK and Run-time, which can be found at [https://dotnet.microsoft.com/en-us/download/dotnet/8.0](https://dotnet.microsoft.com/en-us/download/dotnet/8.0).
+
+1. To configure Visual Studio Code to work with C#, download and install [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) from Microsoft.
+
+**NOTE:** By default, we target the oldest support .NET for the projects contained within this repo. This is done to ensure we are using something other than functionality that is supported at a later version and onward. To target the specific .NET that you downloaded (for example, .NET 8), run the following commands from the root of the repo:
+
+```bash
+find ./ -type f -iname "*.csproj" -not -path "./.git" -exec sed -i.bak 's/<TargetFramework>net6.0<\/TargetFramework>/<TargetFramework>net8.0<\/TargetFramework>/g' "{}" +;
+# if you are comfortable with what was changed, you can delete the backup files by running this command
+# find ./ -type f -iname "*.bak" -not -path "./.git" -exec rm -rf "{}" +;
+```
+
+#### (Alterative) Jetbrains Rider on macOS
+
+For macOS, this is probably by far the easiest option, but this is a paid product with a 30-day trial. Donwload and install Rider at the link below:
+[https://www.jetbrains.com/rider/](https://www.jetbrains.com/rider/)
+
+It will download any required .NET components needed to run the examples. Just open up the `Deepgram.Dev.sln` at the root of the repo. It's that easy.
+
+### Installing on Linux
+
+For Linux, there are two options. The recommended option is [Visual Studio Code](https://code.visualstudio.com/) and the alternative is [Rider by JetBrains](https://www.jetbrains.com/rider/)
+
+#### Linux Build Tools
+
+All Linux distributions have the GNU tools available. The most popular distributions and commands used to install these tools are below.
+
+- Debian/Ubuntu
+
+  ```bash
+  sudo apt update
+  sudo apt install build-essential
+  ```
+
+- Fedora/RHEL/CentOS
+
+  ```bash
+  sudo yum update
+  sudo yum groupinstall "Development Tools"
+  ```
+
+- OpenSUSE
+
+  ```bash
+  sudo zypper update
+  sudo zypper install -t pattern devel_C_C++
+  ```
+
+- Arch
+
+  ```bash
+  sudo pacman -Sy base-devel
+  ```
+
+#### Running and Developing .NET on Linux
+
+1. You can download and install Visual Studio Code here: [https://code.visualstudio.com/Download](https://code.visualstudio.com/Download).
+
+1. Download and install the latest .NET SDK and Run-time, which can be found at [https://dotnet.microsoft.com/en-us/download/dotnet/8.0](https://dotnet.microsoft.com/en-us/download/dotnet/8.0).
+
+1. To configure Visual Studio Code to work with C#, download and install [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) from Microsoft.
+
+**NOTE:** By default we target the oldest support .NET in the projects contained within this repo. This is done to ensure we are using something other than functionality supported at a later version and onward. To target the specific .NET that you downloaded (for example, .NET 8), run the following commands from the root of the repo:
+
+```bash
+find ./ -type f -iname "*.csproj" -not -path "./.git" -exec sed -i.bak 's/<TargetFramework>net6.0<\/TargetFramework>/<TargetFramework>net8.0<\/TargetFramework>/g' "{}" +;
+# if you are comfortable with what was changed, you can delete the backup files by running this command
+# find ./ -type f -iname "*.bak" -not -path "./.git" -exec rm -rf "{}" +;
+```
+
+#### (Alterative) Jetbrains Rider on Linux
+
+For Linux, this is probably by far the easiest option, but this is a paid product with a 30-day trial. Download and install Rider at the link below:
+[https://www.jetbrains.com/rider/](https://www.jetbrains.com/rider/)
+
+It will download any required .NET components needed to run the examples. Just open up the `Deepgram.Dev.sln` at the root of the repo. It's that easy.
+
+### Installing Docker
+
+Some aspects of development require Docker. To install Docker in your development environment, [follow the instructions from the Docker website](https://docs.docker.com/get-docker/).
+
+**Note:** If you are running macOS, ensure that `/usr/local/bin` is in your `PATH`.
+
+## GitHub Workflow
+
+To check out code to work on, please refer to [this guide][github_workflow].
+
+> Attribution: This was in part borrowed from this [document](https://github.com/kubernetes/community/blob/master/contributors/devel/development.md) but tailored for our use case.
+
+[project]: https://github.com/deepgram/deepgram-dotnet-sdk
+[issue]: https://github.com/deepgram/deepgram-dotnet-sdk/issues
+[github_workflow]: https://github.com/deepgram/deepgram-dotnet-sdk/.github/GITHUB_WORKFLOW.md

.github/CODE_OF_CONDUCT.md

@@ -2,7 +2,7 @@
 
 The Deepgram developer community is filled with amazing, clever and creative people, and we're excited for you to join us. Our goal is to create safe and inclusive spaces, have meaningful conversations, and explore ways to make sure that every voice is heard and understood.
 
-#### Being a Good Community Member
+## Being a Good Community Member
 
 Because we prioritize creating a safe space for our members, we believe in actively working on how we, as individuals, can ensure a positive community environment through our own actions and mindsets.
 
@@ -63,7 +63,7 @@ Contribute to the community in a positive and thoughtful way. Consider what’s
 
 Alert community leaders if you notice a dangerous situation, someone in distress, or violations of this Code of Conduct, even if they seem inconsequential.
 
-# Additional rules for online spaces
+## Additional rules for online spaces
 
 For Deepgram’s official online spaces, like our YouTube & Twitch chats, we have some additional rules. Any of the following behaviors can result in a ban without warning.
 
@@ -87,39 +87,39 @@ Please don’t post it or link to it. It doesn’t belong in our online spaces.
 
 Please do not use excessive curse words. Additionally, do not use graphic sexual or violent language — again, think of our spaces as places for people of all ages.
 
-# Enforcement & Reporting
+## Enforcement & Reporting
 
 If you are being harassed by a member of the Deepgram developer community, if you observe someone else being harassed, or you experience actions or behaviors that are contrary to our Code of Conduct, please report the behavior using our [Code of Conduct Report Form](https://developers.deepgram.com/code-of-conduct/report-form/).
 
-## Enforcement Guidelines
+### Enforcement Guidelines
 
 Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
 
-### 1. Correction
+#### 1. Correction
 
 **_Community Impact:_** Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
 
 **_Consequence:_** A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
 
-### 2. Warning
+#### 2. Warning
 
 **_Community Impact:_** A violation through a single incident or series of actions.
 
 **_Consequence:_** A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
 
-### 3. Temporary Ban
+#### 3. Temporary Ban
 
 **_Community Impact:_** A serious violation of community standards, including sustained inappropriate behavior.
 
 **_Consequence:_** A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
 
-### 4. Permanent Ban
+#### 4. Permanent Ban
 
 **_Community Impact:_** Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
 
 **_Consequence:_** A permanent ban from any sort of public interaction within the community.
 
-# Attribution
+## Attribution
 
 This Code of Conduct is adapted from: