Improve CONTRIBUTING.md #1993
Improve CONTRIBUTING.md #1993
Conversation
|
@swift-ci Please test |
|
Speaking of documentation covering contributing to the project, recently I went through all the articles from the "Contributing" section in DocC documentation for SwiftSyntax. If I'm not mistaken, it also contains some outdated documentation. For instance, this one still mentions code from python-time. I wonder if we updated this one; maybe it would be a good time to also take a look at the DocC one? |
|
Thanks for pointing it out, @Matejkob. I updated ChangingSwiftSyntax.md as well. If you find any inconsistencies in the documentation, I encourage you to file issues for them or, even better, to open a PR to update the documentation. |
|
@swift-ci Please test |
CONTRIBUTING.md
Outdated
| ## Building & Testing | ||
|
|
||
| ## Building | ||
| To build swift-syntax, open the package in Xcode, Visual Studio Code with the [Swift for Visual Studio Code](https://github.com/swift-server/vscode-swift) installed, or open it with your favorite text editor and build from the command line using `swift build`. |
There was a problem hiding this comment.
IMO we should call out that it's just a package, something like:
swift-syntax is a SwiftPM package, so you can build and test it using anything that supports packages - opening in Xcode, Visual Studio Code with ..., or through the command line using `swift build` and `swift test`.
Then skipping the You can run... below.
CONTRIBUTING.md
Outdated
| SwiftSyntax is being formatted using [swift-format](http://github.com/apple/swift-format) to ensure a consistent style. | ||
| swift-syntax is formatted using [swift-format](http://github.com/apple/swift-format) to ensure a consistent style. | ||
|
|
||
| To format your changes run `format.py` at the root of this repository. If you have a `swift-format` executable ready, you can pass it to `format.py`. If you do not, `format.py` will build its own copy of `swift-format` in /tmp/swift-format. |
There was a problem hiding this comment.
| To format your changes run `format.py` at the root of this repository. If you have a `swift-format` executable ready, you can pass it to `format.py`. If you do not, `format.py` will build its own copy of `swift-format` in /tmp/swift-format. | |
| To format your changes run `format.py` at the root of this repository. If you have a `swift-format` executable ready, you can pass it to `format.py`. If you do not, `format.py` will build its own copy of `swift-format` in `/tmp/swift-format`. |
| not only identifies it uniquely to Swift Syntax, it also provides a handle that | ||
| other nodes can use to refer to it. The kind of a syntax node defines the | ||
| class of syntax the node belongs to. All nodes are at least of the `Syntax` | ||
| node consists of a kind, which also defines the node’s name, a base kind, and a list of |
There was a problem hiding this comment.
| node consists of a kind, which also defines the node’s name, a base kind, and a list of | |
| node consists of at least a kind (which also defines the node’s name), a base kind, and a list of child nodes |
Is nameForDiagnostics required? If so maybe add that to the list as well. And do you think it would be useful to add a trailing comment to each below, or the documentation in Node is enough?
There was a problem hiding this comment.
nameForDiagnostics is not required. If nil it will use the nameForDiagnostics of the parent node.
I think the documentation of Node is enough. If we duplicate it and change it in the future, we will just forget to update this document again.
My bad for not filing an issue right away. 🙈 I'll make sure to do it properly next time. |
Not a problem. I just wanted to say: Don’t be shy to file issues or PRs about it. |
The document was a little bit outdated. I simplified it to focus on the common development workflows that just open swift-syntax as a SwiftPM package, skipping all paths that go through build-script.py, which shouldn’t be necessary for 95% of all contributors, especially newcomers who this document is designed for.
Update some outdated comments from ChangingSwiftSyntax.md
ahoppen
force-pushed
the
ahoppen/update-contributing
branch
from
a4c9e7e to
e8fc865
Compare
|
@swift-ci Please test |
1 similar comment
|
@swift-ci Please test |
|
@swift-ci Please test macOS |
|
Test failed with looked a bit unrelated |
|
@swift-ci Please test macOS |
1 similar comment
|
@swift-ci Please test macOS |
4 participants
The document was a little bit outdated. I simplified it to focus on the common development workflows that just open swift-syntax as a SwiftPM package, skipping all paths that go through build-script.py, which shouldn’t be necessary for 95% of all contributors, especially newcomers who this document is designed for.