starred/s3fs-fuse

Fork 0

mirror of https://github.com/s3fs-fuse/s3fs-fuse.git synced 2026-04-25 13:26:00 +03:00

[GH-ISSUE #991] Should we split the README.md file into separate files? #550

New issue

Closed

opened 2026-03-04 01:46:39 +03:00 by kerem · 4 comments

kerem commented

2026-03-04 01:46:39 +03:00

Owner

Originally created by @juliogonzalez on GitHub (Mar 23, 2019).
Original GitHub issue: https://github.com/s3fs-fuse/s3fs-fuse/issues/991

FMPOV we could create:

PACKAGES.md
COMPILATION.md
EXAMPLES.md

And move content there (and obviously link it from README.md)

Benefits:

README.md will be smaller and can focus on presenting s3fs-fuse and add links for different instructions.
People can go straight to the point. Questions such as #990 (and others similar in the past) make clear the information is not that easy to find as it could be.

@ggtakec @gaul what's your opinion?

Originally created by @juliogonzalez on GitHub (Mar 23, 2019). Original GitHub issue: https://github.com/s3fs-fuse/s3fs-fuse/issues/991 FMPOV we could create: - PACKAGES.md - COMPILATION.md - EXAMPLES.md And move content there (and obviously link it from README.md) Benefits: - README.md will be smaller and can focus on presenting s3fs-fuse and add links for different instructions. - People can go straight to the point. Questions such as #990 (and others similar in the past) make clear the information is not that easy to find as it could be. @ggtakec @gaul what's your opinion?

kerem closed this issue

2026-03-04 01:46:40 +03:00

kerem commented

2026-03-04 01:46:40 +03:00

Author

Owner

@ggtakec commented on GitHub (Mar 24, 2019):

@juliogonzalez Thank you for the suggestion.
(And thanks @gggeek)

I agree with splitting the README.md file.
However, I would like to consider whether it should be md files, wiki pages, or github pages.
(@gaul and I talked like that last time.)

My current opinion is the following. (In order not to add much files to the s3fs-fuse master repository)

The wiki is a place for short-term FAQs etc.
github pages has all explanation of s3fs
Link from README.md/wiki to github pages

@gaul What about?

@ggtakec commented on GitHub (Mar 24, 2019): @juliogonzalez Thank you for the suggestion. (And thanks @gggeek) I agree with splitting the README.md file. However, I would like to consider whether it should be md files, wiki pages, or github pages. (@gaul and I talked like that last time.) My current opinion is the following. (In order not to add much files to the s3fs-fuse master repository) - The wiki is a place for short-term FAQs etc. - github pages has all explanation of s3fs - Link from README.md/wiki to github pages @gaul What about?

kerem commented

2026-03-04 01:46:41 +03:00

Author

Owner

@juliogonzalez commented on GitHub (Mar 24, 2019):

My 2 cents:

Content that is not tied to versions, should go to the wiki (so they are part of the zip files).
Content that is tied to versions, should be a md file.

(Where are the GitHub packges?)

For example:

Compilation instructions should be md files (those we have at the README.md, and those we have at the Wiki). Not only because dependencies can be different for different versions, but because the instructions themselves can change.
Installation instructions (from packages) should be wiki pages. The package name at distributions is not going to change, and users don't need to worry about anything else.
I am divided about examples, but I guess those could go to the Wiki.
Limitations: as long as they are related to S3, and not to things not implemented at s3fs, they can go to the wiki.
References could stay at main README or be part of the Wiki. I don't have a strong opinion.
FAQ section at the README should stay as it is.
License must stay.

@juliogonzalez commented on GitHub (Mar 24, 2019): My 2 cents: - Content that is not tied to versions, should go to the wiki (so they are part of the zip files). - Content that is tied to versions, should be a md file. (Where are the GitHub packges?) For example: - Compilation instructions should be md files (those we have at the README.md, and those we have at the Wiki). Not only because dependencies can be different for different versions, but because the instructions themselves can change. - Installation instructions (from packages) should be wiki pages. The package name at distributions is not going to change, and users don't need to worry about anything else. - I am divided about examples, but I guess those could go to the Wiki. - Limitations: as long as they are related to S3, and not to things not implemented at s3fs, they can go to the wiki. - References could stay at main README or be part of the Wiki. I don't have a strong opinion. - FAQ section at the README should stay as it is. - License must stay.

kerem commented

2026-03-04 01:46:41 +03:00

Author

Owner

@gaul commented on GitHub (Mar 26, 2019):

I agree that we should simplify the README, although I am mostly happy with the existing structure. Given that most distributions have packages we can relocate the compilation instructions but I like calling out package installation at the top-level. We can streamline the examples; surely IBM support is a niche use case and we probably do not need three fstab examples. The features and especially limitations seem fine as-is; s3fs has different behavior than most FUSE filesystems that we should alert users to.

Creating COMPILATION.md seems reasonable but otherwise I think the wiki does a good job of documentation.

@gaul commented on GitHub (Mar 26, 2019): I agree that we should simplify the README, although I am mostly happy with the existing structure. Given that most distributions have packages we can relocate the compilation instructions but I like calling out package installation at the top-level. We can streamline the examples; surely IBM support is a niche use case and we probably do not need three fstab examples. The features and especially limitations seem fine as-is; s3fs has different behavior than most FUSE filesystems that we should alert users to. Creating COMPILATION.md seems reasonable but otherwise I think the wiki does a good job of documentation.

kerem commented

2026-03-04 01:46:41 +03:00

Author

Owner

@gaul commented on GitHub (Feb 3, 2020):

This seems as good as it will get for now.

@gaul commented on GitHub (Feb 3, 2020): This seems as good as it will get for now.

kerem referenced this issue

2026-03-04 02:00:58 +03:00

[PR #550] [MERGED] Add umount instruction for unplivileged user. #1543