forked from awslabs/mountpoint-s3
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Various documentation updates (awslabs#129)
* Various documentation updates - Document how to configure logging - Update contribution guidelines to point to logging docs and generally be more specific to Mountpoint - Update readme with more details about the alpha release - Update semantics with more notes about concurrent mutations Signed-off-by: James Bornholt <[email protected]> * This has been bothering me Signed-off-by: James Bornholt <[email protected]> --------- Signed-off-by: James Bornholt <[email protected]>
- Loading branch information
1 parent
82d8e03
commit 3590a0f
Showing
6 changed files
with
87 additions
and
39 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,15 +1,13 @@ | ||
| # Contributing Guidelines | ||
|
|
||
| Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional | ||
| documentation, we greatly value feedback and contributions from our community. | ||
| Thank you for your interest in contributing to Mountpoint for Amazon S3. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community. | ||
|
|
||
| Please read through this document before submitting any issues or pull requests to ensure we have all the necessary | ||
| information to effectively respond to your bug report or contribution. | ||
|
|
||
|
|
||
| ## Reporting Bugs/Feature Requests | ||
|
|
||
| We welcome you to use the GitHub issue tracker to report bugs or suggest features. | ||
| Please use the GitHub issue tracker to [report bugs](https://github.com/awslabs/mountpoint-s3/issues/new?assignees=&labels=bug&template=bug-report.yml) or [suggest features](https://github.com/awslabs/mountpoint-s3/issues/new?assignees=&labels=enhancement&template=feature-request.yml). | ||
|
|
||
| When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already | ||
| reported the issue. Please try to include as much information as you can. Details like these are incredibly useful: | ||
|
|
@@ -19,21 +17,23 @@ reported the issue. Please try to include as much information as you can. Detail | |
| * Any modifications you've made relevant to the bug | ||
| * Anything unusual about your environment or deployment | ||
|
|
||
| Logs are also valuable for bug reports. Please read the [logging documentation](LOGGING.md) for details on how to capture logs. | ||
|
|
||
| ## Contributing via Pull Requests | ||
|
|
||
| Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that: | ||
|
|
||
| 1. You are working against the latest source on the *main* branch. | ||
| 2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already. | ||
| 3. You open an issue to discuss any significant work - we would hate for your time to be wasted. | ||
| 3. You open an issue to discuss any significant work -- we would hate for your time to be wasted. | ||
|
|
||
| To send us a pull request, please: | ||
|
|
||
| 1. Fork the repository. | ||
| 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. | ||
| 2. Modify the source. Please focus on the specific change you are contributing; we value multiple small pull requests that are easier to review. | ||
| 3. Ensure local tests pass. | ||
| 4. Commit to your fork using clear commit messages. | ||
| 5. Send us a pull request, answering any default questions in the pull request interface. | ||
| 5. Send us a pull request, answering the default questions in the pull request interface. | ||
| 6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation. | ||
|
|
||
| GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and | ||
|
|
@@ -43,21 +43,18 @@ We require all contributors to agree to the terms of the [Developer Certificate | |
| and to indicate this agreement by signing their commits using [Git's `Signed-off-by` support](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---signoff). | ||
| To add this trailer to your commits, use the `-s, --sign-off` option to `git commit`. | ||
|
|
||
|
|
||
| ## Finding contributions to work on | ||
| 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. | ||
|
|
||
| Looking at the existing issues is a great way to find something to contribute on. We use issue labels to identify [good first issues](https://github.com/awslabs/mountpoint-s3/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) as a great place to start. | ||
|
|
||
| ## Code of Conduct | ||
| This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). | ||
| For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact | ||
| [email protected] with any additional questions or comments. | ||
|
|
||
|
|
||
| ## Security issue notifications | ||
| 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. | ||
|
|
||
| If you discover a potential security issue in this project we ask that you notify AWS Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public GitHub issue. | ||
|
|
||
| ## Licensing | ||
|
|
||
| See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution. | ||
| Mountpoint for Amazon S3 is licensed under the Apache-2.0 license. The pull request template will ask you to confirm the licensing of your contribution and to agree to the [Developer Certificate of Origin (DCO)](https://developercertificate.org/). | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| # Logging | ||
|
|
||
| Mountpoint for Amazon S3 uses the [tracing](https://docs.rs/tracing/latest/tracing/) ecosystem for logging. This makes it easy to configure the verbosity and target of log output. By default we output minimal log information, but for reporting issues or debugging application problems, you may want to customize this logging behavior. | ||
|
|
||
| ## Log outputs | ||
|
|
||
| By default, Mountpoint for Amazon S3 outputs logs to the `~/.mountpoint-s3/` directory, creating it if it doesn't exist. This destination can be changed using the `-l, --log-directory` command-line argument. | ||
|
|
||
| A new log file is created for each execution of `mount-s3`. Log files are never automatically rotated or cleaned up. | ||
|
|
||
| When running in foreground mode (`-f, --foreground`), `mount-s3` also emits the same log information to stdout. | ||
|
|
||
| ## Log details | ||
|
|
||
| By default, we output minimal (error-level) information to the log file. For reporting issues or debugging application problems, it can be helpful to increase this verbosity. We use the common `RUST_LOG` environment variable for controlling log verbosity and subjects. | ||
|
|
||
| To control the log verbosity, set the `RUST_LOG` environment variable. If unset, it defaults to `error` to enable only error-level log messages. Verbosity can be increased by instead setting `RUST_LOG` to `warn`, `info`, `debug`, or `trace`. | ||
|
|
||
| `RUST_LOG` can also control the subjects that are included in the log output. By default, all subjects are included, but verbosity can be configured on a per-subject basis. For example, setting `RUST_LOG` to `trace,awscrt=off` turns on trace-level logging for all subjects except `awscrt`. See the [tracing documentation](https://docs.rs/tracing-subscriber/0.3.16/tracing_subscriber/struct.EnvFilter.html) for more details on how to configure `RUST_LOG`. | ||
|
|
||
| ### Logging suggestions | ||
|
|
||
| For interactive debugging, we often set `RUST_LOG=debug,awscrt=off` to enable debug-level errors for everything except the AWS Common Runtime (the `awscrt` subject). The Common Runtime logging is more verbose, so it's helpful to filter those messages out interactively. | ||
|
|
||
| For reporting issues, we suggest `RUST_LOG=trace,awscrt=debug` as a good default choice. |
Oops, something went wrong.