Merge pull request #438 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,158 @@
+# Development Guide
+
+- [Development Guide](#development-guide)
+  - [Welcome](#welcome)
+  - [Preparing Your Local Operating System](#preparing-your-local-operating-system)
+    - [Setting Up macOS](#setting-up-macos)
+    - [(Optionally) Setting Up Windows](#optional-setting-up-windows)
+  - [Installing Required Software](#installing-required-software)
+    - [Installing on macOS](#installing-on-macos)
+    - [Installing on Linux](#installing-on-linux)
+  - [Installing Python](#installing-python)
+  - [(Optionally) Virtual Environment Manager](#optionally-virtual-environment-manager)
+  - [Installing Docker](#installing-docker)
+  - [GitHub Workflow](#github-workflow)
+
+## Welcome
+
+This document is the canonical source of truth for building and contributing to the [Python 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 a Linux-based operating system. However, it is **HIGHLY** recommended that you have access to a Linux terminal or command prompt. Is this absolutely necessary? No. Will this help out sometime down the road? Yes!
+
+There are two recommended methods to set up your machine. To determine which method is the best choice, you must first determine which version of Windows you are running. To do this, press Windows logo key + R, type winver, and click OK. You may also enter the ver command at the Windows Command Prompt.
+
+- 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).
+- If you're using an earlier version of Windows, create a Linux virtual machine with at least 8GB of memory and 60GB of disk space.
+
+Once you have finished setting up your WSL2 installation or Linux VM, follow the instructions below to configure your system for building and developing code.
+
+**NOTE:** Some `examples` at the root of the repo *may* require modification as they implement Linux SIGTERM signals. This typically tends to be code using the Async IO threading model. Those examples will work on Windows if that code is removed.
+
+## 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.
+
+### Installing on macOS
+
+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).
+
+### Installing on Linux
+
+All Linux distributions have the GNU tools available. Below are the most popular distributions and commands used to install these tools.
+
+- 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
+  ```
+
+### Installing Python
+
+The Python SDK is written in [Python](https://www.python.org/downloads/). To set up a Python development environment, please follow the instructions in this [Python 3 Installation guide](https://realpython.com/installing-python/).
+
+#### (Optionally) Virtual Environment Manager
+
+Once you have installed Python, an optional but **HIGHLY** recommended piece of software is something that will manage virtual environments. This is important because Python projects tend to have software requirements that vary widely between projects, and even those that use the same package may require running different versions of those dependencies.
+
+This will allow you to have multiple environments co-exist together, making it easy to switch between environments as required. There are a number of different options for virtual environment software out there. You can find a list of recommended ones below.
+
+##### Miniconda
+
+Miniconda is a free minimal installer for conda. It is a small bootstrap version of Anaconda that includes only conda.
+
+[https://docs.anaconda.com/miniconda/](https://docs.anaconda.com/miniconda/)
+
+##### venv
+
+The venv module supports creating lightweight "virtual environments", each with their own independent set of Python packages installed in their site directories.
+
+[https://docs.python.org/3/library/venv.html](https://docs.python.org/3/library/venv.html)
+
+##### pyenv
+
+pyenv lets you easily switch between multiple versions of Python. It's simple, unobtrusive, and follows the UNIX tradition of single-purpose tools that do one thing well.
+
+[https://github.com/pyenv/pyenv](https://github.com/pyenv/pyenv)
+
+### 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`.
+
+### Project Specific Software
+
+Once you have the basics, you can download and install any project specific dependencies by navigating to the root your fork and running:
+
+```bash
+make ensure-deps
+```
+
+If you have not forked and `git clone`'ed your fork, please review the next section.
+
+## 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-python-sdk
+[issue]: https://github.com/deepgram/deepgram-python-sdk/issues
+[github_workflow]: https://github.com/deepgram/deepgram-python-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: