Skip to content

Commit 52b022c

Browse files
rubenhoenlerubenhoenle
authored
chore(docs): move contribution guide (#7209)
1 parent 07b831b commit 52b022c

3 files changed

Lines changed: 186 additions & 180 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# Contribute to the STACKIT Go SDK
2+
3+
Your contribution is welcome! Thank you for your interest in contributing to the STACKIT Go SDK. We greatly value your feedback, feature requests, additions to the code, bug reports or documentation extensions.
4+
5+
## Table of contents
6+
7+
- [Developer Guide](#developer-guide)
8+
- [Repository structure](#repository-structure)
9+
- [Implementing a module waiter](#implementing-a-module-waiter)
10+
- [Waiter structure](#waiter-structure)
11+
- [Notes](#notes)
12+
- [Code Contributions](#code-contributions)
13+
- [Bug Reports](#bug-reports)
14+
15+
## Developer Guide
16+
17+
#### Useful Make commands
18+
19+
These commands can be executed from the project root:
20+
21+
- `make project-tools`: get the required dependencies
22+
- `make lint`: lint the code and the examples and sync dependencies. To only lint automatically generated files, run `make lint skip-non-generated-files=true`
23+
- `make test`: run unit tests. To only test automatically generated files, run `make lint skip-non-generated-files=true`
24+
25+
### Repository structure
26+
27+
The STACKIT Go SDK service modules are located under `services`. The files located in `services/[service]` are automatically generated from the [REST API specs](https://github.com/stackitcloud/stackit-api-specifications), whereas the ones located in subfolders (like `wait`) are manually maintained. Therefore, changes to files located in `services/[service]` will not be accepted. Instead, consider proposing changes to the generation process in the [Generator repository](https://github.com/stackitcloud/stackit-sdk-generator).
28+
29+
Inside `core` you can find several packages that are used by all service modules, such as `auth`, `config` and `wait`. Examples of usage of the SDK are located under the `examples` folder.
30+
31+
### Implementing a module waiter
32+
33+
For integration with other tools such as the [STACKIT Terraform Provider](https://github.com/stackitcloud/terraform-provider-stackit) and the [STACKIT CLI](https://github.com/stackitcloud/stackit-cli), there is the need to implement waiters for some SDK modules. Waiters are routines that wait for the completion of asynchronous operations. They are located in a folder named `wait` inside each service folder.
34+
35+
Let's suppose you want to implement the waiters for the `Create`, `Update` and `Delete` operations of a resource `bar` of service `foo`:
36+
37+
1. Start by creating a new folder `wait/` inside `services/foo/`, if it doesn't exist yet
38+
2. Create a file `wait.go` inside your new folder `services/foo/wait`, if it doesn't exist yet. The Go package should be named `wait`.
39+
3. Refer to the [Waiter structure](./CONTRIBUTING.md/#waiter-structure) section for details on the structure of the file and the methods
40+
4. Add unit tests to the wait functions
41+
42+
#### Waiter structure
43+
44+
Below is a typical structure of a waiter for an SDK module:
45+
46+
```go
47+
package wait
48+
49+
import (
50+
"context"
51+
"fmt"
52+
"time"
53+
54+
"github.com/stackitcloud/stackit-sdk-go/core/wait"
55+
"github.com/stackitcloud/stackit-sdk-go/services/foo"
56+
)
57+
58+
const (
59+
CreateSuccess = "CREATE_SUCCEEDED"
60+
CreateFail = "CREATE_FAILED"
61+
UpdateSuccess = "UPDATE_SUCCEEDED"
62+
UpdateFail = "UPDATE_FAILED"
63+
DeleteSuccess = "DELETE_SUCCEEDED"
64+
DeleteFail = "DELETE_FAILED"
65+
)
66+
67+
// APIClientInterface Interfaces needed for tests
68+
type APIClientInterface interface {
69+
GetBarExecute(ctx context.Context, BarId, projectId string) (*foo.GetBarResponse, error)
70+
}
71+
72+
// CreateBarWaitHandler will wait for Bar creation
73+
func CreateBarWaitHandler(ctx context.Context, a APIClientInterface, projectId, barId string) *wait.AsyncActionHandler[foo.GetBarResponse] {
74+
waitConfig := wait.WaiterHelper[foo.GetBarResponse, string]{
75+
FetchInstance: a.GetBar(ctx, projectId, barId).Execute,
76+
GetState: func(d *foo.GetBarResponse) (string, error) {
77+
if d == nil {
78+
return "", errors.New("could not get bar status from response")
79+
}
80+
return d.Status, nil
81+
},
82+
ActiveState: []string{CreateSuccess},
83+
ErrorState: []string{CreateFail},
84+
}
85+
86+
handler := wait.New(waitConfig.Wait())
87+
handler.SetTimeout(45 * time.Minute)
88+
return handler
89+
}
90+
91+
// UpdateBarWaitHandler will wait for Bar update
92+
func UpdateBarWaitHandler(ctx context.Context, a APIClientInterface, BarId, projectId string) *wait.AsyncActionHandler[foo.GetBarResponse] {
93+
waitConfig := wait.WaiterHelper[foo.GetBarResponse, string]{
94+
FetchInstance: a.GetBar(ctx, projectId, barId).Execute,
95+
GetState: func(d *foo.GetBarResponse) (string, error) {
96+
if d == nil {
97+
return "", errors.New("could not get bar status from response")
98+
}
99+
return d.Status, nil
100+
},
101+
ActiveState: []string{UpdateSuccess},
102+
ErrorState: []string{UpdateFail},
103+
}
104+
105+
handler := wait.New(waitConfig.Wait())
106+
handler.SetTimeout(30 * time.Minute)
107+
return handler
108+
}
109+
110+
// DeleteBarWaitHandler will wait for Bar deletion
111+
func DeleteBarWaitHandler(ctx context.Context, a APIClientInterface, BarId, projectId string) *wait.AsyncActionHandler[foo.GetBarResponse] {
112+
waitConfig := wait.WaiterHelper[foo.GetBarResponse, string]{
113+
FetchInstance: a.GetBar(ctx, projectId, barId).Execute,
114+
GetState: func(d *foo.GetBarResponse) (string, error) {
115+
if d == nil {
116+
return "", errors.New("could not get bar status from response")
117+
}
118+
return d.Status, nil
119+
},
120+
ActiveState: []string{DeleteSuccess},
121+
ErrorState: []string{DeleteFail},
122+
}
123+
124+
handler := wait.New(waitConfig.Wait())
125+
handler.SetTimeout(20 * time.Minute)
126+
return handler
127+
}
128+
```
129+
130+
#### Notes
131+
132+
- The success condition may vary from service to service. In the example above we wait for the field `Status` to match a successful or failed message, but other services may have different fields and/or values to represent the state of the create, update or delete operations
133+
- The `id` and the `state` might not be present on the root level of the API response, this also varies from service to service. You must always match the resource `id` and the resource `state` to what is expected
134+
- The timeout values included above are just for reference, each resource takes different amounts of time to finish the create, update or delete operations. You should account for some buffer, e.g. 15 minutes, on top of normal execution times
135+
- For some resources, after a successful delete operation the resource can't be found anymore, so a call to the `Get` method would result in an error. In those cases, the WaiterHelper should have no ActiveStates configured, like in this example:
136+
137+
```go
138+
// DeleteBarWaitHandler will wait for Bar deletion
139+
func DeleteBarWaitHandler(ctx context.Context, a APIClientInterface, barId, projectId string) *wait.AsyncActionHandler[foo.ListBarsResponse] {
140+
waitConfig := wait.WaiterHelper[foo.GetBarResponse, string]{
141+
FetchInstance: a.GetBar(ctx, projectId, barId).Execute,
142+
GetState: func(d *foo.GetBarResponse) (string, error) {
143+
if d == nil {
144+
return "", errors.New("could not get bar status from response")
145+
}
146+
return d.Status, nil
147+
},
148+
ActiveState: nil,
149+
ErrorState: []string{DeleteFail},
150+
DeleteHttpErrorStatusCodes: []int{http.StatusNotFound},
151+
}
152+
153+
handler := wait.New(waitConfig.Wait())
154+
handler.SetTimeout(10 * time.Minute)
155+
return handler
156+
}
157+
158+
```
159+
160+
- The main objective of the waiter functions is to make sure that the operation was successful, which means any other special cases such as intermediate error states should also be handled
161+
162+
## Code Contributions
163+
164+
To make your contribution, follow these steps:
165+
166+
1. Check open or recently closed [Pull Requests](https://github.com/stackitcloud/stackit-sdk-go/pulls) and [Issues](https://github.com/stackitcloud/stackit-sdk-go/issues) to make sure the contribution you are making has not been already tackled by someone else.
167+
2. Fork the repo.
168+
3. Make your changes in a branch that is up-to-date with the original repo's `main` branch.
169+
4. Commit your changes including a descriptive message.
170+
5. Create a pull request with your changes.
171+
6. The pull request will be reviewed by the repo maintainers. If you need to make further changes, make additional commits to keep commit history. When the PR is merged, commits will be squashed.
172+
173+
## Bug Reports
174+
175+
If you would like to report a bug, please open a [GitHub issue](https://github.com/stackitcloud/stackit-sdk-go/issues/new).
176+
177+
To ensure we can provide the best support to your issue, follow these guidelines:
178+
179+
1. Go through the existing issues to check if your issue has already been reported.
180+
2. Make sure you are using the latest version of the SDK modules, we will not provide bug fixes for older versions. Also, latest versions may have the fix for your bug.
181+
3. Please provide as much information as you can about your environment, e.g. your version of Go, your version of the SDK modules, which operating system you are using and the corresponding version.
182+
4. Include in your issue the steps to reproduce it, along with code snippets and/or information about your specific use case. This will make the support process much easier and efficient.

‎CONTRIBUTION.md‎

Lines changed: 3 additions & 179 deletions
Original file line numberDiff line numberDiff line change
@@ -1,182 +1,6 @@
1-
# Contribute to the STACKIT Go SDK
1+
# Moved
22

3-
Your contribution is welcome! Thank you for your interest in contributing to the STACKIT Go SDK. We greatly value your feedback, feature requests, additions to the code, bug reports or documentation extensions.
3+
Our contribution guide has moved to [CONTRIBUTING.md](./CONTRIBUTING.md).
44

5-
## Table of contents
5+
This way we stick to GitHub's standards: [Setting guidelines for repository contributors](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors).
66

7-
- [Developer Guide](#developer-guide)
8-
- [Repository structure](#repository-structure)
9-
- [Implementing a module waiter](#implementing-a-module-waiter)
10-
- [Waiter structure](#waiter-structure)
11-
- [Notes](#notes)
12-
- [Code Contributions](#code-contributions)
13-
- [Bug Reports](#bug-reports)
14-
15-
## Developer Guide
16-
17-
#### Useful Make commands
18-
19-
These commands can be executed from the project root:
20-
21-
- `make project-tools`: get the required dependencies
22-
- `make lint`: lint the code and the examples and sync dependencies. To only lint automatically generated files, run `make lint skip-non-generated-files=true`
23-
- `make test`: run unit tests. To only test automatically generated files, run `make lint skip-non-generated-files=true`
24-
25-
### Repository structure
26-
27-
The STACKIT Go SDK service modules are located under `services`. The files located in `services/[service]` are automatically generated from the [REST API specs](https://github.com/stackitcloud/stackit-api-specifications), whereas the ones located in subfolders (like `wait`) are manually maintained. Therefore, changes to files located in `services/[service]` will not be accepted. Instead, consider proposing changes to the generation process in the [Generator repository](https://github.com/stackitcloud/stackit-sdk-generator).
28-
29-
Inside `core` you can find several packages that are used by all service modules, such as `auth`, `config` and `wait`. Examples of usage of the SDK are located under the `examples` folder.
30-
31-
### Implementing a module waiter
32-
33-
For integration with other tools such as the [STACKIT Terraform Provider](https://github.com/stackitcloud/terraform-provider-stackit) and the [STACKIT CLI](https://github.com/stackitcloud/stackit-cli), there is the need to implement waiters for some SDK modules. Waiters are routines that wait for the completion of asynchronous operations. They are located in a folder named `wait` inside each service folder.
34-
35-
Let's suppose you want to implement the waiters for the `Create`, `Update` and `Delete` operations of a resource `bar` of service `foo`:
36-
37-
1. Start by creating a new folder `wait/` inside `services/foo/`, if it doesn't exist yet
38-
2. Create a file `wait.go` inside your new folder `services/foo/wait`, if it doesn't exist yet. The Go package should be named `wait`.
39-
3. Refer to the [Waiter structure](./CONTRIBUTION.md/#waiter-structure) section for details on the structure of the file and the methods
40-
4. Add unit tests to the wait functions
41-
42-
#### Waiter structure
43-
44-
Below is a typical structure of a waiter for an SDK module:
45-
46-
```go
47-
package wait
48-
49-
import (
50-
"context"
51-
"fmt"
52-
"time"
53-
54-
"github.com/stackitcloud/stackit-sdk-go/core/wait"
55-
"github.com/stackitcloud/stackit-sdk-go/services/foo"
56-
)
57-
58-
const (
59-
CreateSuccess = "CREATE_SUCCEEDED"
60-
CreateFail = "CREATE_FAILED"
61-
UpdateSuccess = "UPDATE_SUCCEEDED"
62-
UpdateFail = "UPDATE_FAILED"
63-
DeleteSuccess = "DELETE_SUCCEEDED"
64-
DeleteFail = "DELETE_FAILED"
65-
)
66-
67-
// APIClientInterface Interfaces needed for tests
68-
type APIClientInterface interface {
69-
GetBarExecute(ctx context.Context, BarId, projectId string) (*foo.GetBarResponse, error)
70-
}
71-
72-
// CreateBarWaitHandler will wait for Bar creation
73-
func CreateBarWaitHandler(ctx context.Context, a APIClientInterface, projectId, barId string) *wait.AsyncActionHandler[foo.GetBarResponse] {
74-
waitConfig := wait.WaiterHelper[foo.GetBarResponse, string]{
75-
FetchInstance: a.GetBar(ctx, projectId, barId).Execute,
76-
GetState: func(d *foo.GetBarResponse) (string, error) {
77-
if d == nil {
78-
return "", errors.New("could not get bar status from response")
79-
}
80-
return d.Status, nil
81-
},
82-
ActiveState: []string{CreateSuccess},
83-
ErrorState: []string{CreateFail},
84-
}
85-
86-
handler := wait.New(waitConfig.Wait())
87-
handler.SetTimeout(45 * time.Minute)
88-
return handler
89-
}
90-
91-
// UpdateBarWaitHandler will wait for Bar update
92-
func UpdateBarWaitHandler(ctx context.Context, a APIClientInterface, BarId, projectId string) *wait.AsyncActionHandler[foo.GetBarResponse] {
93-
waitConfig := wait.WaiterHelper[foo.GetBarResponse, string]{
94-
FetchInstance: a.GetBar(ctx, projectId, barId).Execute,
95-
GetState: func(d *foo.GetBarResponse) (string, error) {
96-
if d == nil {
97-
return "", errors.New("could not get bar status from response")
98-
}
99-
return d.Status, nil
100-
},
101-
ActiveState: []string{UpdateSuccess},
102-
ErrorState: []string{UpdateFail},
103-
}
104-
105-
handler := wait.New(waitConfig.Wait())
106-
handler.SetTimeout(30 * time.Minute)
107-
return handler
108-
}
109-
110-
// DeleteBarWaitHandler will wait for Bar deletion
111-
func DeleteBarWaitHandler(ctx context.Context, a APIClientInterface, BarId, projectId string) *wait.AsyncActionHandler[foo.GetBarResponse] {
112-
waitConfig := wait.WaiterHelper[foo.GetBarResponse, string]{
113-
FetchInstance: a.GetBar(ctx, projectId, barId).Execute,
114-
GetState: func(d *foo.GetBarResponse) (string, error) {
115-
if d == nil {
116-
return "", errors.New("could not get bar status from response")
117-
}
118-
return d.Status, nil
119-
},
120-
ActiveState: []string{DeleteSuccess},
121-
ErrorState: []string{DeleteFail},
122-
}
123-
124-
handler := wait.New(waitConfig.Wait())
125-
handler.SetTimeout(20 * time.Minute)
126-
return handler
127-
}
128-
```
129-
130-
#### Notes
131-
132-
- The success condition may vary from service to service. In the example above we wait for the field `Status` to match a successful or failed message, but other services may have different fields and/or values to represent the state of the create, update or delete operations
133-
- The `id` and the `state` might not be present on the root level of the API response, this also varies from service to service. You must always match the resource `id` and the resource `state` to what is expected
134-
- The timeout values included above are just for reference, each resource takes different amounts of time to finish the create, update or delete operations. You should account for some buffer, e.g. 15 minutes, on top of normal execution times
135-
- For some resources, after a successful delete operation the resource can't be found anymore, so a call to the `Get` method would result in an error. In those cases, the WaiterHelper should have no ActiveStates configured, like in this example:
136-
137-
```go
138-
// DeleteBarWaitHandler will wait for Bar deletion
139-
func DeleteBarWaitHandler(ctx context.Context, a APIClientInterface, barId, projectId string) *wait.AsyncActionHandler[foo.ListBarsResponse] {
140-
waitConfig := wait.WaiterHelper[foo.GetBarResponse, string]{
141-
FetchInstance: a.GetBar(ctx, projectId, barId).Execute,
142-
GetState: func(d *foo.GetBarResponse) (string, error) {
143-
if d == nil {
144-
return "", errors.New("could not get bar status from response")
145-
}
146-
return d.Status, nil
147-
},
148-
ActiveState: nil,
149-
ErrorState: []string{DeleteFail},
150-
DeleteHttpErrorStatusCodes: []int{http.StatusNotFound},
151-
}
152-
153-
handler := wait.New(waitConfig.Wait())
154-
handler.SetTimeout(10 * time.Minute)
155-
return handler
156-
}
157-
158-
```
159-
160-
- The main objective of the waiter functions is to make sure that the operation was successful, which means any other special cases such as intermediate error states should also be handled
161-
162-
## Code Contributions
163-
164-
To make your contribution, follow these steps:
165-
166-
1. Check open or recently closed [Pull Requests](https://github.com/stackitcloud/stackit-sdk-go/pulls) and [Issues](https://github.com/stackitcloud/stackit-sdk-go/issues) to make sure the contribution you are making has not been already tackled by someone else.
167-
2. Fork the repo.
168-
3. Make your changes in a branch that is up-to-date with the original repo's `main` branch.
169-
4. Commit your changes including a descriptive message.
170-
5. Create a pull request with your changes.
171-
6. The pull request will be reviewed by the repo maintainers. If you need to make further changes, make additional commits to keep commit history. When the PR is merged, commits will be squashed.
172-
173-
## Bug Reports
174-
175-
If you would like to report a bug, please open a [GitHub issue](https://github.com/stackitcloud/stackit-sdk-go/issues/new).
176-
177-
To ensure we can provide the best support to your issue, follow these guidelines:
178-
179-
1. Go through the existing issues to check if your issue has already been reported.
180-
2. Make sure you are using the latest version of the SDK modules, we will not provide bug fixes for older versions. Also, latest versions may have the fix for your bug.
181-
3. Please provide as much information as you can about your environment, e.g. your version of Go, your version of the SDK modules, which operating system you are using and the corresponding version.
182-
4. Include in your issue the steps to reproduce it, along with code snippets and/or information about your specific use case. This will make the support process much easier and efficient.

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -261,7 +261,7 @@ If you encounter any issues or have suggestions for improvements, please open an
261261

262262
## Contribute
263263

264-
Your contribution is welcome! For more details on how to contribute, refer to our [Contribution Guide](./CONTRIBUTION.md).
264+
Your contribution is welcome! For more details on how to contribute, refer to our [Contribution Guide](./CONTRIBUTING.md).
265265

266266
## Release creation
267267

0 commit comments

Comments
 (0)