mirror of
https://github.com/nickpoida/og-aws.git
synced 2025-03-09 15:40:06 +00:00
Update contributing notes.
This commit is contained in:
Joshua Levy
parent
63043f5409
commit
94efd2185e
2 changed files with 35 additions and 12 deletions
|
|
@ -1,30 +1,35 @@
|
|||
Contributing
|
||||
------------
|
||||
|
||||
Contributions of all kinds, including discussion, corrections, additions, and improvements, are welcome! We hope you'll join and help, in small ways or large. We gladly credit all contributors and authors. Here are few notes before you jump in.
|
||||
Contributions of all kinds, including discussion, corrections, additions, and improvements, are welcome! We hope you'll join and help, in small ways or large. We gladly [credit](/AUTHORS.md) all contributors. Here are few notes before you jump in.
|
||||
|
||||
[](https://og-aws.slack.lexikon.io/) [](https://airtable.com/shrXZ61VrovWfXYBg)
|
||||
|
||||
The simplest thing you can do to contribute is [**join the Slack channel**](https://og-aws.slack.lexikon.io/) or [**add to our list of common questions**](https://airtable.com/shrXZ61VrovWfXYBg), which help guide us in ways to improve the guide.
|
||||
### Please Help
|
||||
|
||||
[**File issues**](https://github.com/open-guides/og-aws/issues) if it’s clear what needs to be improved. (For less well-defined issues, discussing first on Slack may be helpful.)
|
||||
If you’ve found this guide useful, you have many ways to help:
|
||||
|
||||
[**Pull requests**](https://github.com/open-guides/og-aws/pulls) with changes are even better. Please keep them small and focused, so we can add items individually, and review the conventions below. (Again, Slack discussion can help.)
|
||||
- The simplest thing you can do to contribute is [**join the Slack channel**](https://og-aws.slack.lexikon.io/) or [**add to our list of common questions**](https://airtable.com/shrXZ61VrovWfXYBg), which helps the community and guides what contributors can focus on. We encourage you to ask AWS questions and help others!
|
||||
- [**File issues**](https://github.com/open-guides/og-aws/issues) if it’s clear something needs to be improved and you’re not able to make a pull request.
|
||||
- [**Pull requests**](https://github.com/open-guides/og-aws/pulls) with changes are always welcome. Please keep them small and focused, so we can add items individually, and review the conventions below. If you want to make a larger change, try to discuss it in Slack.
|
||||
- [**Review**] or [**comment**] on existing issues and pull requests if you have expertise.
|
||||
- If you have deep expertise, consider offering to be an **editor** or **expert**. Editors and experts are assigned roles that [help us review the guide](#editorial-process). Join Slack to discuss this.
|
||||
|
||||
Please review current issues and pull requests to avoid duplication.
|
||||
|
||||
We gladly [credit](/AUTHORS.md) all contributors.
|
||||
### Pull Request Etiquette
|
||||
|
||||
Finally, if an issue isn’t appropriate, or if you might have skills and inclination to help improve the guide in a more substantial way, please shoot an e-mail to [@jlevy](https://github.com/jlevy).
|
||||
- Keep changes as small as is practical. Do not make changes to multiple sections at once, alter whitespace in broad ways, etc.
|
||||
- Neutrality: If you have an affiliation related to what you are changing, please disclose it.
|
||||
- Please do your best to review current issues and pull requests to avoid duplication.
|
||||
|
||||
### Style
|
||||
### Writing Style
|
||||
|
||||
- **Use references:** If you are adding an item, whenever possible, try to add a link or reference to relevant discussion or reference pages.
|
||||
- **Link to references:** If you are adding an item, whenever possible, try to add a link or reference to relevant discussion or reference pages.
|
||||
- **Be brief:** Avoid long expository paragraphs; it’s better to link to a blog. (We are open to linking to your own blog, if it’s the best source.)
|
||||
- **Include opinions and common practice:** Thoughtful opinion is helpful. If there are multiple conventions or ideas on something held by experts, mention the different ones.
|
||||
- **Clarity:** Strive for consistency with conventions listed here, but clarity is most important.
|
||||
|
||||
### Conventions
|
||||
### Writing Conventions
|
||||
|
||||
When you contribute, keep in mind these conventions:
|
||||
|
||||
|
|
@ -48,3 +53,19 @@ When you contribute, keep in mind these conventions:
|
|||
- Note we try to make sections uniquely titled, so GitHub links to Markdown section anchors don’t collide and are stable.
|
||||
|
||||
Note we keep consistent formatting in Markdown via [markdownfmt](https://github.com/shurcooL/markdownfmt). We run **admin/reformat.sh** to do this, but you don’t have to worry about it unless you really want to.
|
||||
|
||||
### Editorial Process
|
||||
|
||||
- Roles:
|
||||
- **project leads:** General direction of process and overall quality of the Guide
|
||||
- **editors:** Contributors own specific sections or aspects of the guide, usually by topic/section, reviewing PRs and contributing; requires expert knowledge
|
||||
- **experts:** People with expert knowledge in various areas, who have agreed to review or help on demand with tougher questions or PRs
|
||||
- **contributors:** Everyone who helps one way or another
|
||||
- All PRs are reviewed by an **editor** and for non-trivial changes, a **project lead**, usually in that order, but it can be reversed for expediency.
|
||||
- In addition, anyone with relevant knowledge is encouraged to review/comment on PRs
|
||||
- Both editors and project leads are responsible for checking for style or problems
|
||||
- Trivial changes may me merged in directly by project leads or editors
|
||||
|
||||
### Contact
|
||||
|
||||
If you have concerns or additional ideas of ways to help, contact [@jlevy](https://github.com/jlevy) (e-mail or DM on Slack).
|
||||
|
|
|
|||
|
|
@ -4,6 +4,8 @@ The Open Guide to Amazon Web Services
|
|||
=====================================
|
||||
|
||||
[](https://og-aws.slack.lexikon.io/) [](https://airtable.com/shrXZ61VrovWfXYBg)
|
||||
[Authors](AUTHORS.md)
|
||||
[Contributing](CONTRIBUTING.md)
|
||||
|
||||
Table of Contents
|
||||
-----------------
|
||||
|
|
@ -628,7 +630,7 @@ S3
|
|||
- S3 has a [static website hosting option](http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html) that is simply a setting that enables configurable HTTP index and error pages and [HTTP redirect support](http://docs.aws.amazon.com/AmazonS3/latest/dev/how-to-page-redirect.html) to [public content](http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteAccessPermissionsReqd.html) in S3. It’s a simple way to host static assets or a fully static website.
|
||||
- Consider using CloudFront in front of most or all assets:
|
||||
- Like any CDN, CloudFront improves performance significantly.
|
||||
- 🔸SSL is only supported on the built-in amazonaws.com domain for S3. S3 supports serving these sites through a [custom domain](http://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html), but [not over SSL on a custom domain](http://stackoverflow.com/questions/11201316/how-to-configure-ssl-for-amazon-s3-bucket). However, [CloudFront allows you to serve a custom domain over https](http://docs.aws.amazon.com/acm/latest/userguide/gs-cf.html). Amazon provides free SNI SSL/TLS certificates via Amazon Certificate Manager. [SNI does not work on very outdated browsers/operating systems](https://en.wikipedia.org/wiki/Server_Name_Indication#Support). Alternatively, you can provide your own certificate to use on CloudFront to support all browsers/operating systems.
|
||||
- 🔸SSL is only supported on the built-in amazonaws.com domain for S3. S3 supports serving these sites through a [custom domain](http://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html), but [not over SSL on a custom domain](http://stackoverflow.com/questions/11201316/how-to-configure-ssl-for-amazon-s3-bucket). However, [CloudFront allows you to serve a custom domain over https](http://docs.aws.amazon.com/acm/latest/userguide/gs-cf.html). Amazon provides free SNI SSL/TLS certificates via Amazon Certificate Manager. [SNI does not work on very outdated browsers/operating systems](https://en.wikipedia.org/wiki/Server_Name_Indication#Support). Alternatively, you can provide your own certificate to use on CloudFront to support all browsers/operating systems.
|
||||
- 🔸If you are including resources across domains, such as fonts inside CSS files, you may need to [configure CORS](https://docs.aws.amazon.com/AmazonS3/latest/dev/cors.html) for the bucket serving those resources.
|
||||
- Since pretty much everything is moving to SSL nowadays, and you likely want control over the domain, you probably want to set up CloudFront with your own certificate in front of S3 (and to ignore the [AWS example on this](http://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html) as it is non-SSL only).
|
||||
- That said, if you do, you’ll need to think through invalidation or updates on CloudFront. You may wish to [include versions or hashes in filenames](https://abhishek-tiwari.com/post/CloudFront-design-patterns-and-best-practices) so invalidation is not necessary.
|
||||
|
|
@ -1174,7 +1176,7 @@ CloudFront
|
|||
- 🚪CDNs are [a highly fragmented market](https://www.datanyze.com/market-share/cdn/). CloudFront has grown to be a leader, but many alternatives that might better suit specific needs.
|
||||
|
||||
### CloudFront Tips
|
||||
- 🐥**IPv6** is [now supported](https://aws.amazon.com/about-aws/whats-new/2016/10/ipv6-support-for-cloudfront-waf-and-s3-transfer-acceleration/)!
|
||||
- 🐥**IPv6** is [now supported](https://aws.amazon.com/about-aws/whats-new/2016/10/ipv6-support-for-cloudfront-waf-and-s3-transfer-acceleration/)!
|
||||
- 🐥**HTTP/2** is [now supported](https://aws.amazon.com/about-aws/whats-new/2016/09/amazon-cloudfront-now-supports-http2/)! Clients [must support TLS 1.2 and SNI](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-values-specify.html#DownloadDistValuesSupportedHTTPVersions).
|
||||
- While the most common use is for users to browse and download content (GET or HEAD methods) requests, CloudFront also supports ([since 2013](https://aws.amazon.com/blogs/aws/amazon-cloudfront-content-uploads-post-put-other-methods/)) uploaded data (POST, PUT, DELETE, OPTIONS, and PATCH).
|
||||
- You must enable this by specifying the [allowed HTTP methods](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-values-specify.html#DownloadDistValuesAllowedHTTPMethods) when you create the distribution.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue