Overhaul README and documentation catalog to introduce best practices
#363
Conversation
This file contains hidden or 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
FranzBusch
force-pushed
the
fb-readme-doc-overhaul
branch
from
3db3c66 to
0ac66ff
Compare
ktoso
reviewed
Jul 8, 2025
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
|
Shouldn't we keep the section about implementing a Line 153 in 81d3d07 |
|
@sebsto I have another document that moves this into a guide. You mind if I land this in a follow-up? |
|
@FranzBusch Great ! I just wanted to be sure it's not forgotten |
weissi
reviewed
Jul 8, 2025
FranzBusch
force-pushed
the
fb-readme-doc-overhaul
branch
2 times, most recently
from
d72cf2c to
2ae3e90
Compare
ktoso
approved these changes
Jul 8, 2025
heckj
reviewed
Jul 8, 2025
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
FranzBusch
force-pushed
the
fb-readme-doc-overhaul
branch
from
2ae3e90 to
15c3584
Compare
heckj
suggested changes
Jul 8, 2025
There was a problem hiding this comment.
The top level page for swift-docs is pretty long - it may benefit from breaking up into separate articles on getting started and core concepts, but I don't think that's critically needed for this update.
I went back with my fine-toothed comb and suggested some punctuation, grammar, and style fixes - and restricting the best practices page to use ## Topics to make it a page that explicitly links to others (aka API Topic Reference page) to hold the best practices without a lot of extra redundancy.
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
czechboy0
reviewed
Jul 8, 2025
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
FranzBusch
force-pushed
the
fb-readme-doc-overhaul
branch
2 times, most recently
from
0ac334b to
3ac92c6
Compare
FranzBusch
force-pushed
the
fb-readme-doc-overhaul
branch
2 times, most recently
from
25106b1 to
929bce2
Compare
tib
approved these changes
Jul 9, 2025
czechboy0
reviewed
Jul 9, 2025
Sources/Logging/Docs.docc/BestPractices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
# Motivation `SwiftLog` was created before DocC existed which meant that most of the documentation was part of the `README` and we had a pretty bare bones documentation catalog. We also have a second source of guidelines from the SSWG. This results in a currently unsatisfying developer experience where everyone has to go around looking for the content in mostly undocumented places. # Modifications This PR overhauls the `README` and moves most of the content into the documentation catalog. It also introduces a new section called "Best practices" that are intended to replace the logging guides on swift.org so that the content moves closer to where it belongs. To showcase such a best practice this PR brings over the log level recommendation of swift.org. The recommendation is mostly the same except that after recent discussions we wanted to allow libraries to log at `info` level when they encounter problems which they can't communicate through other channels e.g. by throwing from a method. # Result With this PR we provide a nicer experience to our developers making it easier for them to get started and understand how to properly log. We also set ourselves up for expanding on the best practices around logging.
FranzBusch
force-pushed
the
fb-readme-doc-overhaul
branch
from
929bce2 to
8908b0d
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation
SwiftLogwas created before DocC existed which meant that most of the documentation was part of theREADMEand we had a pretty bare bones documentation catalog. We also have a second source of guidelines from the SSWG. This results in a currently unsatisfying developer experience where everyone has to go around looking for the content in mostly undocumented places.Modifications
This PR overhauls the
READMEand moves most of the content into the documentation catalog. It also introduces a new section called "Best practices" that are intended to replace the logging guides on swift.org so that the content moves closer to where it belongs. To showcase such a best practice this PR brings over the log level recommendation of swift.org. The recommendation is mostly the same except that after recent discussions we wanted to allow libraries to log atinfolevel when they encounter problems which they can't communicate through other channels e.g. by throwing from a method.Result
With this PR we provide a nicer experience to our developers making it easier for them to get started and understand how to properly log. We also set ourselves up for expanding on the best practices around logging.