Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Flatten the structure a little reduce a level from TOC #3199

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Flatten the structure a little reduce a level from TOC #3199

wants to merge 1 commit into from

Conversation

LPardue
Copy link
Contributor

@LPardue LPardue commented Aug 22, 2025

This is one proposal for addressing the point raised in #3169.

Currently, the bulk of the spec is located in Section 4. We have an entire spec for the topic of resumable uploads, so being shy to use top-level sections for key concepts might be a bit conservative. This PR flattens the structure (but doesn't move any sections around) in order to reduce the amount of third-level sections, making space to only define the new headers in them. (FWIW 4th-level TOC items tend to indicate over-nesting and don't always get rendered in the TOC)

Landing this would number sections and be slightly disruptive to open reviews/issues. If we like the direction, I'd suggest holding it until other issues are closed out.

Current ToC (ignoring appendices)

   1.  Introduction
   2.  Conventions and Definitions
   3.  Overview
     3.1.  Example 1: Complete upload of representation data with
           known size
     3.2.  Example 2: Upload as a series of parts
   4.  Upload Resource
     4.1.  State
       4.1.1.  Offset
       4.1.2.  Completeness
       4.1.3.  Length
       4.1.4.  Limits
     4.2.  Upload Creation
       4.2.1.  Client Behavior
       4.2.2.  Server Behavior
       4.2.3.  Examples
     4.3.  Offset Retrieval
       4.3.1.  Client Behavior
       4.3.2.  Server Behavior
       4.3.3.  Example
     4.4.  Upload Append
       4.4.1.  Client Behavior
       4.4.2.  Server Behavior
       4.4.3.  Example
     4.5.  Upload Cancellation
       4.5.1.  Client Behavior
       4.5.2.  Server Behavior
       4.5.3.  Example
     4.6.  Concurrency
   5.  Status Code 104 (Upload Resumption Supported)
   6.  Media Type application/partial-upload
   7.  Problem Types
     7.1.  Mismatching Offset
     7.2.  Completed Upload
     7.3.  Inconsistent Length
   8.  Content Codings
   9.  Transfer Codings
   10. Integrity Digests
     10.1.  Representation Digests
     10.2.  Content Digests
   11. Responses to Uploads
   12. Upload Strategies
     12.1.  Optimistic Upload Creation
       12.1.1.  Upgrading To Resumable Uploads
     12.2.  Careful Upload Creation
   13. Security Considerations
   14. IANA Considerations
     14.1.  HTTP Fields
     14.2.  HTTP Status Code
     14.3.  Media Type
     14.4.  HTTP Problem Types
   15. References
     15.1.  Normative References
     15.2.  Informative References

Proposed Toc (ignoring appendices)

   1.  Introduction
   2.  Conventions and Definitions
   3.  Overview
     3.1.  Example 1: Complete upload of representation data with
           known size
     3.2.  Example 2: Upload as a series of parts
   4.  Upload Resource
     4.1.  Offset
       4.1.1.  Upload-Offset
     4.2.  Completeness
       4.2.1.  Upload-Complete
     4.3.  Length
       4.3.1.  Upload-Length
     4.4.  Limits
       4.4.1.  Upload-Limits
   5.  Upload Creation
     5.1.  Client Behavior
     5.2.  Server Behavior
     5.3.  Examples
   6.  Offset Retrieval
     6.1.  Client Behavior
     6.2.  Server Behavior
     6.3.  Example
   7.  Upload Append
     7.1.  Client Behavior
     7.2.  Server Behavior
     7.3.  Example
   8.  Upload Cancellation
     8.1.  Client Behavior
     8.2.  Server Behavior
     8.3.  Example
   9.  Concurrency
   10. Status Code 104 (Upload Resumption Supported)
   11. Media Type application/partial-upload
   12. Problem Types
     12.1.  Mismatching Offset
     12.2.  Completed Upload
     12.3.  Inconsistent Length
   13. Content Codings
   14. Transfer Codings
   15. Integrity Digests
     15.1.  Representation Digests
     15.2.  Content Digests
   16. Responses to Uploads
   17. Upload Strategies
     17.1.  Optimistic Upload Creation
       17.1.1.  Upgrading To Resumable Uploads
     17.2.  Careful Upload Creation
   18. Security Considerations
   19. IANA Considerations
     19.1.  HTTP Fields
     19.2.  HTTP Status Code
     19.3.  Media Type
     19.4.  HTTP Problem Types
   20. References
     20.1.  Normative References
     20.2.  Informative References

@LPardue LPardue mentioned this pull request Aug 22, 2025
Open
@LPardue LPardue mentioned this pull request Sep 1, 2025
Open
Acconut
Acconut approved these changes Oct 2, 2025
View reviewed changes
Copy link
Member

@Acconut Acconut left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great suggestion, thank you!

@LPardue LPardue marked this pull request as draft October 2, 2025 16:37
@LPardue
Copy link
Contributor Author

LPardue commented Oct 2, 2025

Thanks for the feedback. Based on the number of comments/issues we received on the published draft. I suggest holding this change. Perhaps even published as a standalone I-D revision to ensure the WG can more easily spot the deltas. Hence, I've marked it as draft for now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Acconut Acconut Acconut approved these changes

@guoye-zhang guoye-zhang guoye-zhang approved these changes

Assignees

No one assigned

Labels

resumable-upload

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@LPardue @Acconut @guoye-zhang @reschke