Skip to content

Commit 7f246d9

Browse files
leplatremleplatrem
authored
Fix #505: add missing bits of SysEng quality standards (#510)
* Fix #505: add missing bits of SysEng quality standards * Add ADR about actions configuration
1 parent de69798 commit 7f246d9

File tree

4 files changed

+178
-0
lines changed

4 files changed

+178
-0
lines changed

‎CONTRIBUTING.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
First off, thanks for taking the time to contribute! ❤️
2+
3+
All types of contributions are encouraged and valued.
4+
5+
Before doing so, here are a few guidelines:
6+
7+
* You agree to license your contributions under the project [license](LICENSE).
8+
* Use pull-requests early so it's open for discussion, even if your
9+
contribution isn't ready yet.
10+
* All pull requests should include tests, as they help us avoid regressions in
11+
our code.
12+
* A pull-request adding functionality should also update the documentation
13+
accordingly.

‎README.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ graph TD
3434
* [Actions](docs/actions.md)
3535
* [Deployment](docs/deployment.md)
3636
* [Troubleshooting](docs/troubleshooting.md)
37+
* [RRA for JBI](https://docs.google.com/document/d/1p0wWVNK5V1jXKAOE-3EquBVcGOIksHD6Rgz9afZQ1A4/edit?usp=sharing)
3738

3839
## Usage
3940

@@ -50,6 +51,12 @@ graph TD
5051
- `make lint`: static analysis of the code base
5152
- `make format`: automatically format code to align to linting standards
5253

54+
In order to pass arguments to `pytest`:
55+
56+
```
57+
poetry run pytest -vv -k test_bugzilla_list_webhooks
58+
```
59+
5360
You may consider:
5461

5562
* Tweaking the application settings in the `.env` file (See [jbi/environment.py](../jbi/environment.py) for details)

‎docs/adrs/001-actions-reusability.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Composability of Actions
2+
3+
- Status: accepted
4+
- Date: 2022-10-05
5+
6+
Tracking issue: https://github.com/mozilla/jira-bugzilla-integration/pull/232
7+
8+
## Context and Problem Statement
9+
10+
The gap between the default action behavior and custom workflow is too hard.
11+
How to improve composability of workflows? How can we make it easier for customers
12+
to create their own workflows without us?
13+
14+
## Decision Drivers
15+
16+
- Amount of efforts
17+
- Code readability
18+
- Reusability
19+
- Configuration
20+
- Testability
21+
22+
## Considered Options
23+
24+
1. Add parameters to default action
25+
2. Split default action into reusable steps
26+
27+
## Decision Outcome
28+
29+
Chosen option: "[option 2]", because the amount of efforts to refactor
30+
the actions code is justified by the benefits in terms of readability,
31+
testability, reusability. The resulting configuration can be verbose, but
32+
will be explicit.
33+
34+
## Pros and Cons of the Options
35+
36+
### Option 1 - Add parameters to default action
37+
38+
With this approach, we introduce parameters to the default action class, in
39+
order to enable or disable certain parts of its workflow.
40+
41+
```yaml
42+
whiteboard_tag: example
43+
module: jbi.actions.default
44+
parameters:
45+
jira_project_key: EXMPL
46+
sync_whiteboard_labels: false
47+
update_issue_resolution: true
48+
```
49+
50+
- **Amount of efforts**: Low. Almost no refactoring necessary.
51+
- **Code readability**: Bad. Having several combinations of parameters will result in a lot of code branches. Plus, in order to implement custom workflows, contributors will inherit the default action, which will result in a lot of indirections.
52+
- **Reusability**: Bad. Reusing some bits of the default action won't be trivial without inheriting classes.
53+
- **Configuration**: Easy. Document all available parameters.
54+
- **Testability**: Bad. The number of combinations for all parameters can be huge and hard to test.
55+
56+
### Option 2 - Split default action into reusable steps
57+
58+
With this approach, we split the default action class into tiny functions called "steps".
59+
The configuration lists the steps to be executed by context, whether a comment is
60+
posted, a bug is created, or updated.
61+
62+
```yaml
63+
whiteboard_tag: example
64+
module: jbi.actions.default
65+
parameters:
66+
jira_project_key: EXMPL
67+
steps:
68+
new:
69+
- create_issue
70+
- add_link_to_bugzilla
71+
- add_link_to_jira
72+
existing:
73+
- update_issue
74+
- add_jira_comments_for_changes
75+
comment:
76+
- create_comment
77+
```
78+
79+
- **Amount of efforts**: High. The whole action code and its tests has to be refactored.
80+
- **Code readability**: Great. Each step has its own limited scope.
81+
- **Reusability**: Great. Reusing steps is trivial.
82+
- **Configuration**: Verbose. Each workflow will repeat all necessary steps. It could also be hard to differentiate
83+
workflows if the list of steps is too long.
84+
- **Testability**: Great. Each step has a limited scope, and is follows the functional programming paradigm.

‎docs/adrs/template.md

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# [short title of solved problem and solution]
2+
3+
- Status: [proposed | rejected | accepted | deprecated | … | superseded by
4+
[ADR-0005](0005-example.md)] <!-- optional -->
5+
- Date: [YYYY-MM-DD when the decision was last updated] <!-- optional -->
6+
7+
Tracking issue: [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
12+
three sentences. You may want to articulate the problem in form of a question.]
13+
14+
## Decision Drivers <!-- optional -->
15+
16+
- [driver 1, e.g., a force, facing concern, …]
17+
- [driver 2, e.g., a force, facing concern, …]
18+
- … <!-- numbers of drivers can vary -->
19+
20+
## Considered Options
21+
22+
1. [option 1]
23+
2. [option 2]
24+
3. [option 3]
25+
4. … <!-- numbers of options can vary -->
26+
27+
## Decision Outcome
28+
29+
Chosen option: "[option 1]", because [justification. e.g., only option, which
30+
meets k.o. criterion decision driver | which resolves force force | … | comes
31+
out best (see below)].
32+
33+
### Positive Consequences <!-- optional -->
34+
35+
- [e.g., improvement of quality attribute satisfaction, follow-up decisions
36+
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 1 - …
47+
48+
[example | description | pointer to more information | …] <!-- optional -->
49+
50+
- Good, because [argument a]
51+
- Bad, because [argument b]
52+
- … <!-- numbers of pros and cons can vary -->
53+
54+
### Option 2 - …
55+
56+
[example | description | pointer to more information | …] <!-- optional -->
57+
58+
- Good, because [argument a]
59+
- Bad, because [argument b]
60+
- … <!-- numbers of pros and cons can vary -->
61+
62+
### Option 3 - …
63+
64+
[example | description | pointer to more information | …] <!-- optional -->
65+
66+
- Good, because [argument a]
67+
- Bad, because [argument b]
68+
- … <!-- numbers of pros and cons can vary -->
69+
70+
## Links <!-- optional -->
71+
72+
- [Link type] [Link to ADR]
73+
<!-- example: Refined by [ADR-0005](0005-example.md) -->
74+
- … <!-- numbers of links can vary -->

0 commit comments

Comments
 (0)