Skip to content

Commit bb38180

Browse files
hackebrothackebrot
authored
Merge pull request #36 from mozilla-services/add-adr-for-using-go
Add ADR for using Go 📝
2 parents 89699fa + 1f9142c commit bb38180

File tree

2 files changed

+171
-0
lines changed

2 files changed

+171
-0
lines changed

‎docs/adr/001-go-with-github-api-clients.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Adopting Go with Trusted GitHub API Clients
2+
3+
* Status: **accepted** 👍
4+
* Deciders: [@hackebrot] [@dlactin]
5+
* Date: 2025-03-31
6+
7+
Technical Story: This decision addresses issues discussed in Jira tickets
8+
[CICD-45] and [CICD-439].
9+
10+
[CICD-45]: https://mozilla-hub.atlassian.net/browse/CICD-45
11+
[CICD-439]: https://mozilla-hub.atlassian.net/browse/CICD-439
12+
13+
[@hackebrot]: https://github.com/hackebrot
14+
[@dlactin]: https://github.com/dlactin
15+
16+
## Context and Problem Statement
17+
18+
The Four Keys BigQuery dataset currently lacks historical data because it only
19+
ingests events (such as Git commit pushes, deployments, and incidents) as they
20+
occur through GitHub webhooks. This real-time approach leaves a data gap that
21+
limits the completeness of our retroactive deployment analysis.
22+
23+
Furthermore, the current method for measuring `Lead Time for Changes` links
24+
deployments to pushes using a single commit SHA. This approach fails to capture
25+
all relevant commits—particularly those from earlier pushes that were not
26+
deployed—and assumes an immutable git history, which is not always the case. By
27+
leveraging the GitHub APIs for retroactive data collection, we can fill this
28+
historical data gap and capture all relevant commit information, thereby
29+
enhancing the accuracy of our deployment-related metrics.
30+
31+
## Decision Drivers
32+
33+
1. **Retroactive Data Collection Capability:**
34+
The solution must facilitate the retrieval of historical data via the GitHub
35+
APIs, effectively addressing the gaps in the Four Keys dataset.
36+
2. **Stability and Maturity:**
37+
The solution must leverage well-established libraries that have proven
38+
reliability in production environments.
39+
3. **Maintenance and Support:**
40+
The selected tools must be actively maintained and well-documented, with
41+
strong community or official support to ensure long-term viability.
42+
4. **Team Expertise and Ecosystem Fit:**
43+
It should align with the team's existing skills and integrate smoothly with
44+
our current infrastructure and technology stack (e.g., Kubernetes, Argo CD).
45+
46+
## Considered Options
47+
48+
* A. Python with packages like `PyGitHub` and `gql`
49+
* B. Go with packages like `github.com/shurcooL/githubv4` and `github.com/google/go-github/v68/github`
50+
* C. Custom-Built API Wrappers
51+
52+
## Decision Outcome
53+
54+
Chosen option:
55+
56+
**B. Go with packages like `github.com/shurcooL/githubv4` and `github.com/google/go-github/v68/github`**
57+
58+
Option B was selected because it best satisfies our key decision drivers. Go’s
59+
strong compile-time type safety, combined with the maturity and active
60+
maintenance of the selected packages, ensures production-ready support for the
61+
GitHub GraphQL API. Additionally, Go aligns well with our team's expertise and
62+
technology stack (e.g., Kubernetes, Argo CD).
63+
64+
While Python offers advantages in rapid prototyping, its available GitHub API
65+
libraries lack the specialized stability and GitHub-specific support required
66+
for this project.
67+
68+
Furthermore, developing custom API wrappers was ruled out due to the
69+
significantly higher development and maintenance overhead, and the risk of
70+
re-implementing functionality already well-supported by mature libraries.
71+
72+
## Links
73+
74+
* Go client library for accessing the GitHub GraphQL API v4: https://github.com/shurcooL/githubv4
75+
* Go client library for accessing the GitHub REST API v3: https://github.com/google/go-github
76+
* Python client library for accessing the GitHub REST API v3: https://pypi.org/project/PyGithub/
77+
* General purpose Python GraphQL client: https://pypi.org/project/gql/

‎docs/adr/template.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# [short title of solved problem and solution]
2+
3+
* Status: [proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)] <!-- optional -->
4+
* Deciders: [list everyone involved in the decision] <!-- optional -->
5+
* Date: [YYYY-MM-DD when the decision was last updated] <!-- optional -->
6+
7+
Technical Story: [description | ticket/issue URL] <!-- optional -->
8+
9+
## Context and Problem Statement
10+
11+
[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.]
12+
13+
## Decision Drivers <!-- optional -->
14+
15+
1. [primary driver, e.g., a force, facing concern, …]
16+
2. [secondary driver, e.g., a force, facing concern, …]
17+
3. … <!-- numbers of drivers can vary, ranked in order of importance -->
18+
19+
## Considered Options
20+
21+
* A. [option A]
22+
* B. [option B]
23+
* C. [option C]
24+
* D. … <!-- numbers of options can vary -->
25+
26+
## Decision Outcome
27+
28+
Chosen option:
29+
30+
**A. [option A]**
31+
32+
[justification. e.g., only option, which meets primary decision driver | which resolves a force or facing concern | … | comes out best (see below)].
33+
34+
### Positive Consequences <!-- optional -->
35+
36+
* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]
37+
* …
38+
39+
### Negative Consequences <!-- optional -->
40+
41+
* [e.g., compromising quality attribute, follow-up decisions required, …]
42+
* …
43+
44+
## Pros and Cons of the Options <!-- optional -->
45+
46+
### [option A]
47+
48+
[example | description | pointer to more information | …] <!-- optional -->
49+
50+
#### Pros
51+
52+
* [argument for]
53+
* [argument for]
54+
* … <!-- numbers of pros can vary -->
55+
56+
#### Cons
57+
58+
* [argument against]
59+
* … <!-- numbers of cons can vary -->
60+
61+
### [option B]
62+
63+
[example | description | pointer to more information | …] <!-- optional -->
64+
65+
#### Pros
66+
67+
* [argument for]
68+
* [argument for]
69+
* … <!-- numbers of pros can vary -->
70+
71+
#### Cons
72+
73+
* [argument against]
74+
* … <!-- numbers of cons can vary -->
75+
76+
### [option C]
77+
78+
[example | description | pointer to more information | …] <!-- optional -->
79+
80+
#### Pros
81+
82+
* [argument for]
83+
* [argument for]
84+
* … <!-- numbers of pros can vary -->
85+
86+
#### Cons
87+
88+
* [argument against]
89+
* … <!-- numbers of cons can vary -->
90+
91+
## Links <!-- optional -->
92+
93+
* [Link type] [Link to ADR] <!-- example: Refined by [ADR-0005](0005-example.md) -->
94+
* … <!-- numbers of links can vary -->

0 commit comments

Comments
 (0)