From 70538117405ebad4bcd439601aa4759bad15d9e9 Mon Sep 17 00:00:00 2001 From: Christopher Zamplas Date: Mon, 15 Jun 2026 14:52:53 -0400 Subject: [PATCH 1/3] docs: add object naming best practices --- content/docs/tips.md | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/content/docs/tips.md b/content/docs/tips.md index d1f4b70..db5fa3f 100644 --- a/content/docs/tips.md +++ b/content/docs/tips.md @@ -20,4 +20,32 @@ If you have a tool to add to the list, please let the OSN team know at {{< help- | **Tool** | **Language** | **Platform** | |----------|--------------|--------------| | [Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) | Python | All | -| [aws.s3](https://cloud.r-project.org/web/packages/aws.s3/index.html) | R | All | \ No newline at end of file +| [aws.s3](https://cloud.r-project.org/web/packages/aws.s3/index.html) | R | All | + +## Best Practices + +### Naming Conventions + +S3 permits many special characters in object names, but some tools and libraries may interpret them differently. For example, a name containing a plus sign (`+`) may conflict with an otherwise identical name containing a space: + +```text +test file.txt +test+file.txt +``` + +Names that differ only by capitalization may also conflict when used with some tools or filesystems: + +```text +test file.txt +Test File.txt +``` + +Forward slashes (`/`) may be used to separate folders or directories in a path, such as: + +```text +project/data/test file.txt +``` + +However, a forward slash should not be used within the name of an individual file or directory. + +For broad compatibility with tools, libraries, and filesystems, use lower-case letters, numbers, spaces, hyphens (`-`), underscores (`_`), and periods (`.`) in file and folder names. Avoid unnecessary special characters, names that differ only by capitalization, and leading or trailing spaces or periods. From 17c5d6bf353e09aaf7ca3815eb38e50bb1273633 Mon Sep 17 00:00:00 2001 From: NTchrist <8462489+NTchrist@users.noreply.github.com> Date: Wed, 24 Jun 2026 13:12:22 -0400 Subject: [PATCH 2/3] docs: revise naming convention guidance as requested --- content/docs/tips.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/tips.md b/content/docs/tips.md index db5fa3f..79acf29 100644 --- a/content/docs/tips.md +++ b/content/docs/tips.md @@ -26,6 +26,8 @@ If you have a tool to add to the list, please let the OSN team know at {{< help- ### Naming Conventions +For broad compatibility with tools, libraries, and filesystems: use lower-case letters, numbers, spaces, hyphens (`-`), underscores (`_`), and periods (`.`) in file and folder names. Avoid unnecessary special characters, names that differ only by capitalization, and leading or trailing spaces or periods. + S3 permits many special characters in object names, but some tools and libraries may interpret them differently. For example, a name containing a plus sign (`+`) may conflict with an otherwise identical name containing a space: ```text @@ -40,12 +42,10 @@ test file.txt Test File.txt ``` -Forward slashes (`/`) may be used to separate folders or directories in a path, such as: +Forward slashes (`/`) may be used to separate "folders" or "directories" in a path, such as: ```text project/data/test file.txt ``` However, a forward slash should not be used within the name of an individual file or directory. - -For broad compatibility with tools, libraries, and filesystems, use lower-case letters, numbers, spaces, hyphens (`-`), underscores (`_`), and periods (`.`) in file and folder names. Avoid unnecessary special characters, names that differ only by capitalization, and leading or trailing spaces or periods. From 0b48585b285dec021820d07578e8087337d271de Mon Sep 17 00:00:00 2001 From: NTchrist <8462489+NTchrist@users.noreply.github.com> Date: Wed, 24 Jun 2026 13:20:28 -0400 Subject: [PATCH 3/3] docs: added consequence to guidance --- content/docs/tips.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/tips.md b/content/docs/tips.md index 79acf29..a670c79 100644 --- a/content/docs/tips.md +++ b/content/docs/tips.md @@ -26,7 +26,7 @@ If you have a tool to add to the list, please let the OSN team know at {{< help- ### Naming Conventions -For broad compatibility with tools, libraries, and filesystems: use lower-case letters, numbers, spaces, hyphens (`-`), underscores (`_`), and periods (`.`) in file and folder names. Avoid unnecessary special characters, names that differ only by capitalization, and leading or trailing spaces or periods. +For broad compatibility with tools, libraries, and filesystems: use lower-case letters, numbers, spaces, hyphens (`-`), underscores (`_`), and periods (`.`) in file and folder names. Avoid unnecessary special characters, names that differ only by capitalization, and leading or trailing spaces or periods. Deviating from this may result in data that is unreadable in certain circumstances. S3 permits many special characters in object names, but some tools and libraries may interpret them differently. For example, a name containing a plus sign (`+`) may conflict with an otherwise identical name containing a space: