Skip to content

Commit 5696c35

Browse files
author
Zahi Ben Shabat
committed
update contribution page
1 parent 662737b commit 5696c35

File tree

3 files changed

+214
-27
lines changed

3 files changed

+214
-27
lines changed

‎CONTRIBUTING.md

Lines changed: 10 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
1-
---
2-
sidebar_position: 12
3-
---
4-
51
## Contributing
62

73
Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional
@@ -108,9 +104,9 @@ Questions to consider when designing new provider:
108104
Start with designing the architecture that will meet the particular type of workloads this provider needs to support. <br/>
109105
Express the architecture with your choice of IAC(CDK, TF, Pulumi etc.)
110106

111-
:::idea
107+
<br/>
112108
example: building an ECS provider - will require an AWS ECS cluster - which also requires a VPC and support for logs, encryption and load balancer to allow access to the containers. an AWS ECR is also required to store the container images.
113-
:::
109+
<br/>
114110

115111
**Step 2**<br/>
116112
Define the *Provisioning role* and *Operations role* permissions - this needs to be reason with the expected user interactions and IAC requirements. It is best practice to set your roles with least privileges permissions.
@@ -120,9 +116,9 @@ Configure an appropriate pipeline to deploy and update this provider
120116

121117
**Step 4**<br/>
122118
Create a provider backstage template and load the template to the backstage-reference repository
123-
:::tip
119+
<br/>
124120
Don't forget to update all-templates.yaml with your new template path
125-
:::
121+
<br/>
126122

127123
#### Test your provider
128124
**Step 1**<br/>
@@ -154,25 +150,25 @@ Questions to consider when designing a new application pattern:
154150
**Step 1**<br/>
155151
Start with designing the architecture that for this type of workload, this include the desired runtime(Java, .Net, python etc.), the resource that compose this application express by IAC(CDK, TF, Pulumi)
156152

157-
:::idea
153+
<br/><br/>
158154
example: building an ECS application - will require an AWS ECS Task and Task definition , in addition the application log will need a log group and you may need to add additional supporting resources such as RDS database or S3 bucket. The application IAC will have dependencies on expected resources such as an existing VPC or ECS cluster. this will be provided by the corresponding selected environment and injected to the application repository. the pipeline will stich all this together and express those arguments as environment variables
159-
:::
155+
<br/>
160156

161157
**Step 2**<br/>
162158
Define the identity of the application in a shape of an IAM role. This application identity role is used not only to describe the current permission the application needs but also the future permission the application may be granted as a result of the *resource binding* process.
163159

164-
:::tip
160+
<br/><br/>
165161
Make sure you IAC supports external ingestion of JSON permission policies. [See DeclareJSONStatements example here](https://github.com/awslabs/app-development-for-backstage-io-on-aws/blob/main/backstage-reference/common/aws_ecs/src/cdk-ecs-module-stack.ts)
166-
:::
162+
<br/>
167163

168164
**Step 3**<br/>
169165
Configure an appropriate pipeline to deploy and update this application
170166

171167
**Step 4**<br/>
172168
Create an application backstage template and load the template to the backstage-reference repository
173-
:::tip
169+
<br/><br/>
174170
Don't forget to update all-templates.yaml with your new template path
175-
:::
171+
<br/>
176172

177173
#### Test your application
178174
**Step 1**<br/>

‎website/docs/CONTRIBUTING.md

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
---
2+
sidebar_position: 12
3+
---
4+
5+
## Contributing
6+
7+
Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional
8+
documentation, we greatly value feedback and contributions from our community.
9+
10+
Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
11+
information to effectively respond to your bug report or contribution.
12+
13+
14+
### Reporting Bugs/Feature Requests
15+
16+
We welcome you to use the GitHub issue tracker to report bugs or suggest features.
17+
18+
When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already
19+
reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
20+
21+
* A reproducible test case or series of steps
22+
* The version of our code being used
23+
* Any modifications you've made relevant to the bug
24+
* Anything unusual about your environment or deployment
25+
26+
27+
### Contributing via Pull Requests
28+
Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
29+
30+
1. You are working against the latest source on the *main* branch.
31+
2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
32+
3. You open an issue to discuss any significant work - we would hate for your time to be wasted.
33+
34+
To send us a pull request, please:
35+
36+
1. Fork the repository.
37+
2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
38+
3. Ensure local tests pass.
39+
4. Commit to your fork using clear commit messages.
40+
5. Send us a pull request, answering any default questions in the pull request interface.
41+
6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
42+
43+
GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
44+
[creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
45+
46+
47+
### Finding contributions to work on
48+
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
49+
50+
51+
### Code of Conduct
52+
This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
53+
For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
54+
[email protected] with any additional questions or comments.
55+
56+
57+
### Security issue notifications
58+
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.
59+
60+
61+
### Licensing
62+
63+
See the [LICENSE](https://github.com/awslabs/app-development-for-backstage-io-on-aws/blob/main/LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
64+
65+
66+
## Contributing Assets to OPA on AWS
67+
68+
Thank you for considering a contribution to OPA on AWS project!
69+
The above described guidelines are to set the standard of submitting Pull Request, That is in conjunction to the below description
70+
71+
### Contribution Type
72+
73+
1. Contributing OPA on AWS Templates
74+
1. Provider Template
75+
2. App Template
76+
3. Resource Template
77+
4. Other Template
78+
2. Contributing OPA on AWS Pipelines
79+
1. New pipeline pattern
80+
2. Update existing pipeline pattern
81+
3. Contributing OPA on AWS Core modifications
82+
1. Change in UI / Frontend of OPA on AWS plugins
83+
2. Change in SDK API / Backend of OPA on AWS Plugins
84+
3. Change in sacffolder actions
85+
4. Change in architecture or platform design
86+
5. Change in common interfaces
87+
4. Contributing OPA on AWS extensions
88+
1. Integration with new tools and plugins
89+
2. Integration with additional Backstage.io APIs / entities
90+
3. Extending OPA on AWS model
91+
92+
### Submitting Contribution
93+
94+
Before submitting any contribution type please make sure it adheres to the OPA on AWS [architecture](/website/docs/techdocs/architecture.md)
95+
96+
### Contributing an OPA on AWS provider
97+
98+
Questions to consider when designing new provider:
99+
1. Why do i need a new provider? does the existing providers support the type of application I'm trying to build?
100+
2. What is the common environment this provider support for applications?
101+
3. Does the new provider type supports multiple applications that share the same requirements?
102+
4. Do i have clarity on the roles and permissions required to implement this provider?
103+
5. Do i have clarity on the resources and architecture required to implement this provider?
104+
6. Will this provider support backwards upgrades? what will be the effect of applications if the provider were to be updated?
105+
106+
#### Build your provider
107+
**Step 1**<br/>
108+
Start with designing the architecture that will meet the particular type of workloads this provider needs to support. <br/>
109+
Express the architecture with your choice of IAC(CDK, TF, Pulumi etc.)
110+
111+
:::idea
112+
example: building an ECS provider - will require an AWS ECS cluster - which also requires a VPC and support for logs, encryption and load balancer to allow access to the containers. an AWS ECR is also required to store the container images.
113+
:::
114+
115+
**Step 2**<br/>
116+
Define the *Provisioning role* and *Operations role* permissions - this needs to be reason with the expected user interactions and IAC requirements. It is best practice to set your roles with least privileges permissions.
117+
118+
**Step 3**<br/>
119+
Configure an appropriate pipeline to deploy and update this provider
120+
121+
**Step 4**<br/>
122+
Create a provider backstage template and load the template to the backstage-reference repository
123+
:::tip
124+
Don't forget to update all-templates.yaml with your new template path
125+
:::
126+
127+
#### Test your provider
128+
**Step 1**<br/>
129+
Make sure you are able to provision your new provider template.
130+
We highly recommend to test different context for this step as described in the [test-cases](/website/docs/tests.md)
131+
132+
**Step 2**<br/>
133+
Make sure you can update the provider configurations or IAC and the pipeline will apply the changes succufully
134+
135+
**Step 3**<br/>
136+
Add entries in [test-cases](/website/docs/tests.md) document for the new provider implemented.
137+
138+
#### Submit your PR
139+
Submit a pull request for the new provider following the instructions in this page.
140+
141+
142+
### Contributing an OPA on AWS application
143+
144+
Questions to consider when designing a new application pattern:
145+
146+
1. Who is the team that going to be using this application template? does it address their requirements?
147+
2. What pattern this new application introduce? is there already an existing pattern that can be used?
148+
3. Does this application can use an existing environment or it requires a new environment type / provider? if so, see the above *Contributing an OPA on AWS provider*
149+
4. What kind of permissions and resources this application needs?
150+
5. What kind of operational actions this application need? which of them can be supported through a pipeline and which one needs a UI of platform changes?
151+
6. Will this application support upgrades? what will be the effect of the deployed applications if we were to be update it?
152+
153+
#### Build your application
154+
**Step 1**<br/>
155+
Start with designing the architecture that for this type of workload, this include the desired runtime(Java, .Net, python etc.), the resource that compose this application express by IAC(CDK, TF, Pulumi)
156+
157+
:::idea
158+
example: building an ECS application - will require an AWS ECS Task and Task definition , in addition the application log will need a log group and you may need to add additional supporting resources such as RDS database or S3 bucket. The application IAC will have dependencies on expected resources such as an existing VPC or ECS cluster. this will be provided by the corresponding selected environment and injected to the application repository. the pipeline will stich all this together and express those arguments as environment variables
159+
:::
160+
161+
**Step 2**<br/>
162+
Define the identity of the application in a shape of an IAM role. This application identity role is used not only to describe the current permission the application needs but also the future permission the application may be granted as a result of the *resource binding* process.
163+
164+
:::tip
165+
Make sure you IAC supports external ingestion of JSON permission policies. [See DeclareJSONStatements example here](https://github.com/awslabs/app-development-for-backstage-io-on-aws/blob/main/backstage-reference/common/aws_ecs/src/cdk-ecs-module-stack.ts)
166+
:::
167+
168+
**Step 3**<br/>
169+
Configure an appropriate pipeline to deploy and update this application
170+
171+
**Step 4**<br/>
172+
Create an application backstage template and load the template to the backstage-reference repository
173+
:::tip
174+
Don't forget to update all-templates.yaml with your new template path
175+
:::
176+
177+
#### Test your application
178+
**Step 1**<br/>
179+
Make sure you are able to provision your new application template.
180+
We highly recommend to test different context for this step as described in the [test-cases](/website/docs/tests.md).
181+
You should also test provisioning another application on the same environment to make sure there's not conflict of configurations and/or resources.
182+
183+
**Step 2**<br/>
184+
1. Make sure you can update the application configurations or IAC and the pipeline will apply the changes successfully
185+
2. Make sure you can update the application code /src and CD pipeline will build and deploy the new application
186+
187+
**Step 3**<br/>
188+
Add entries in [test-cases](/website/docs/tests.md) document for the new application implemented.
189+
190+
#### Submit your PR
191+
Submit a pull request for the new provider following the instructions in this page.

‎website/docusaurus.config.ts

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -193,21 +193,21 @@ const config: Config = {
193193
name: "content",
194194
sourceBaseUrl: "https://raw.githubusercontent.com/awslabs/app-development-for-backstage-io-on-aws/main/",
195195
outDir: "docs",
196-
documents: ["CHANGELOG.md", "CONTRIBUTING.md"],
196+
documents: ["CHANGELOG.md"],
197197
performCleanup: true,
198198
// in the plugin's options:
199-
modifyContent(filename, content) {
200-
if (filename.includes("CONTRIBUTING")) {
201-
const re = /\[LICENSE\]\(LICENSE\)/g;
202-
const licenseUrl = "https://github.com/awslabs/app-development-for-backstage-io-on-aws/blob/main/LICENSE"
203-
var newContent = content.replace(re, `[LICENSE](${licenseUrl})`);
204-
return {
205-
content: newContent
206-
}
207-
}
208-
// don't want to modify this item, since it doesn't contain "CONTRIBUTING" in the name
209-
return undefined
210-
},
199+
// modifyContent(filename, content) {
200+
// if (filename.includes("CONTRIBUTING")) {
201+
// const re = /\[LICENSE\]\(LICENSE\)/g;
202+
// const licenseUrl = "https://github.com/awslabs/app-development-for-backstage-io-on-aws/blob/main/LICENSE"
203+
// var newContent = content.replace(re, `[LICENSE](${licenseUrl})`);
204+
// return {
205+
// content: newContent
206+
// }
207+
// }
208+
// // don't want to modify this item, since it doesn't contain "CONTRIBUTING" in the name
209+
// return undefined
210+
// },
211211
}]
212212
],
213213
}

0 commit comments

Comments
 (0)