Skip to content

Commit 22dc7d0

Browse files
davidvonthenendavidvonthenen
authored
Merge pull request #438 from dvonthenen/project-contribution-docs
Defining the Contribution Process and Project Management Process
2 parents 2595d9f + b3355b0 commit 22dc7d0

File tree

6 files changed

+590
-47
lines changed

6 files changed

+590
-47
lines changed

‎.github/BRANCH_AND_RELEASE_PROCESS.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Branch and Release Process
2+
3+
- [Branch and Release Process](#branch-and-release-process)
4+
- [Branching Process](#branching-process)
5+
- [Branching Methods](#branching-methods)
6+
- [Branch Process for This Project](#branch-process-for-this-project)
7+
- [Why Pick This Strategy?](#why-pick-this-strategy)
8+
- [Release Process](#release-process)
9+
10+
## Branching Process
11+
12+
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.
13+
14+
## Branching Methods
15+
16+
For open-source projects, three popular Git branching strategies are:
17+
18+
1. **Git Flow**:
19+
20+
Git Flow is a robust branching strategy that uses multiple branches for feature development, releases, and hotfixes. The primary branches include:
21+
22+
- `main`: Holds the production-ready code.
23+
- `develop`: Integrates all completed features and serves as the staging area for the next release.
24+
- `feature/*`: Branches off from `develop` for new features.
25+
- `release/*`: Branches off from `develop` when preparing a new release.
26+
- `hotfix/*`: Branches off from `main` for critical fixes that need to be deployed immediately.
27+
28+
Git Flow is suitable for projects with regular release cycles and helps maintain a clear and structured workflow.
29+
30+
2. **GitHub Flow**:
31+
32+
GitHub Flow is a simpler, more streamlined approach ideal for projects that deploy frequently. Its key principles include:
33+
34+
- A single `main` branch always containing deployable code.
35+
- Branches for each feature or bug fix that branch off from `main` and merge back into `main` upon completion.
36+
- Continuous deployment from the `main` branch, allowing for fast iterations and rapid delivery of new features.
37+
38+
This strategy emphasizes simplicity and continuous integration, making it well-suited for fast-paced development environments.
39+
40+
3. **Trunk-Based Development**:
41+
42+
Trunk-Based Development focuses on keeping a single, stable branch (the "trunk") where all developers commit their code. Key practices include:
43+
44+
- Small, frequent commits directly to the `main` branch.
45+
- Short-lived feature branches that are quickly merged back into `main`.
46+
- Emphasis on automated testing and continuous integration to ensure code stability.
47+
This strategy aims to minimize merge conflicts and maintain a high level of code quality, promoting rapid feedback and collaboration.
48+
49+
Each of these strategies has its own strengths and is chosen based on the specific needs and workflow of the project.
50+
51+
## Branch Process for This Project
52+
53+
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:
54+
55+
Aspects used from **GitHub Flow**:
56+
57+
- A single `main` branch always containing deployable code.
58+
- Branches for each feature or bug fix that branch off from `main` and merge back into `main` upon completion.
59+
- Continuous deployment from the `main` branch, allowing for fast iterations and rapid delivery of new features.
60+
61+
Aspects used from **Git Flow**:
62+
63+
- `release-v[0-9]+/*`: Branches off from `main` when preparing a new release.
64+
- `hotfix/*`: Branches off from `main` (or a release branch) for critical fixes that need to be deployed immediately.
65+
66+
### Why Pick This Strategy?
67+
68+
This is done in order to foster:
69+
70+
- maximum collaboration with external contributors
71+
- 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)
72+
- it's intuitively obvious where contributions (ie PRs) need to merge with zero background on the project
73+
- this puts all bespoke, project, and repo management on the project maintainers
74+
- forces the project maintainers to embrace CI/CD
75+
- `main` must work at all times; therefore, main can be deployed or released at all times
76+
- things don't always go according to plan
77+
- having the branching strategy for releases **Git Flow** helps support of concurrent versions
78+
- provides flexibilty to create release trains
79+
80+
## Release Process
81+
82+
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.
83+
84+
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.
85+
86+
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.
87+
88+
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

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Development Guide
2+
3+
- [Development Guide](#development-guide)
4+
- [Welcome](#welcome)
5+
- [Preparing Your Local Operating System](#preparing-your-local-operating-system)
6+
- [Setting Up macOS](#setting-up-macos)
7+
- [(Optionally) Setting Up Windows](#optional-setting-up-windows)
8+
- [Installing Required Software](#installing-required-software)
9+
- [Installing on macOS](#installing-on-macos)
10+
- [Installing on Linux](#installing-on-linux)
11+
- [Installing Python](#installing-python)
12+
- [(Optionally) Virtual Environment Manager](#optionally-virtual-environment-manager)
13+
- [Installing Docker](#installing-docker)
14+
- [GitHub Workflow](#github-workflow)
15+
16+
## Welcome
17+
18+
This document is the canonical source of truth for building and contributing to the [Python SDK][project].
19+
20+
Please submit an [issue] on GitHub if you:
21+
22+
- Notice a requirement that this doc does not capture.
23+
- Find a different doc that specifies requirements (the doc should instead link here).
24+
25+
## Preparing Your Local Operating System
26+
27+
Where needed, each piece of required software will have separate instructions for Linux, Windows, or macOS.
28+
29+
### Setting Up macOS
30+
31+
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/).
32+
33+
In particular, this command installs the necessary packages:
34+
35+
```bash
36+
brew install coreutils ed findutils gawk gnu-sed gnu-tar grep make jq
37+
```
38+
39+
You will want to include this block or something similar at the end of your `.bashrc` or shell init script:
40+
41+
```bash
42+
GNUBINS="$(find `brew --prefix`/opt -type d -follow -name gnubin -print)"
43+
44+
for bindir in ${GNUBINS[@]}
45+
do
46+
export PATH=$bindir:$PATH
47+
done
48+
49+
export PATH
50+
```
51+
52+
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/)
53+
54+
### (Optional) Setting Up Windows
55+
56+
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!
57+
58+
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.
59+
60+
- 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).
61+
- 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.
62+
63+
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.
64+
65+
**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.
66+
67+
## Installing Required Software
68+
69+
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.
70+
71+
### Installing on macOS
72+
73+
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).
74+
75+
### Installing on Linux
76+
77+
All Linux distributions have the GNU tools available. Below are the most popular distributions and commands used to install these tools.
78+
79+
- Debian/Ubuntu
80+
81+
```bash
82+
sudo apt update
83+
sudo apt install build-essential
84+
```
85+
86+
- Fedora/RHEL/CentOS
87+
88+
```bash
89+
sudo yum update
90+
sudo yum groupinstall "Development Tools"
91+
```
92+
93+
- OpenSUSE
94+
95+
```bash
96+
sudo zypper update
97+
sudo zypper install -t pattern devel_C_C++
98+
```
99+
100+
- Arch
101+
102+
```bash
103+
sudo pacman -Sy base-devel
104+
```
105+
106+
### Installing Python
107+
108+
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/).
109+
110+
#### (Optionally) Virtual Environment Manager
111+
112+
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.
113+
114+
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.
115+
116+
##### Miniconda
117+
118+
Miniconda is a free minimal installer for conda. It is a small bootstrap version of Anaconda that includes only conda.
119+
120+
[https://docs.anaconda.com/miniconda/](https://docs.anaconda.com/miniconda/)
121+
122+
##### venv
123+
124+
The venv module supports creating lightweight "virtual environments", each with their own independent set of Python packages installed in their site directories.
125+
126+
[https://docs.python.org/3/library/venv.html](https://docs.python.org/3/library/venv.html)
127+
128+
##### pyenv
129+
130+
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.
131+
132+
[https://github.com/pyenv/pyenv](https://github.com/pyenv/pyenv)
133+
134+
### Installing Docker
135+
136+
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/).
137+
138+
**Note:** If you are running macOS, ensure that `/usr/local/bin` is in your `PATH`.
139+
140+
### Project Specific Software
141+
142+
Once you have the basics, you can download and install any project specific dependencies by navigating to the root your fork and running:
143+
144+
```bash
145+
make ensure-deps
146+
```
147+
148+
If you have not forked and `git clone`'ed your fork, please review the next section.
149+
150+
## GitHub Workflow
151+
152+
To check out code to work on, please refer to [this guide][github_workflow].
153+
154+
> 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.
155+
156+
[project]: https://github.com/deepgram/deepgram-python-sdk
157+
[issue]: https://github.com/deepgram/deepgram-python-sdk/issues
158+
[github_workflow]: https://github.com/deepgram/deepgram-python-sdk/.github/GITHUB_WORKFLOW.md

‎.github/CODE_OF_CONDUCT.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
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.
44

5-
#### Being a Good Community Member
5+
## Being a Good Community Member
66

77
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.
88

@@ -63,7 +63,7 @@ Contribute to the community in a positive and thoughtful way. Consider what’s
6363

6464
Alert community leaders if you notice a dangerous situation, someone in distress, or violations of this Code of Conduct, even if they seem inconsequential.
6565

66-
# Additional rules for online spaces
66+
## Additional rules for online spaces
6767

6868
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.
6969

@@ -87,39 +87,39 @@ Please don’t post it or link to it. It doesn’t belong in our online spaces.
8787

8888
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.
8989

90-
# Enforcement & Reporting
90+
## Enforcement & Reporting
9191

9292
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/).
9393

94-
## Enforcement Guidelines
94+
### Enforcement Guidelines
9595

9696
Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
9797

98-
### 1. Correction
98+
#### 1. Correction
9999

100100
**_Community Impact:_** Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
101101

102102
**_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.
103103

104-
### 2. Warning
104+
#### 2. Warning
105105

106106
**_Community Impact:_** A violation through a single incident or series of actions.
107107

108108
**_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.
109109

110-
### 3. Temporary Ban
110+
#### 3. Temporary Ban
111111

112112
**_Community Impact:_** A serious violation of community standards, including sustained inappropriate behavior.
113113

114114
**_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.
115115

116-
### 4. Permanent Ban
116+
#### 4. Permanent Ban
117117

118118
**_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.
119119

120120
**_Consequence:_** A permanent ban from any sort of public interaction within the community.
121121

122-
# Attribution
122+
## Attribution
123123

124124
This Code of Conduct is adapted from:
125125

0 commit comments

Comments
 (0)