Skip to content

revamp user guides #1257

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
Merged
merged 7 commits into from
Mar 7, 2025
Merged

revamp user guides #1257

merged 7 commits into from
Mar 7, 2025

Conversation

OmarTawfik
Copy link
Contributor

@OmarTawfik OmarTawfik commented Feb 26, 2025 •
edited
Loading

  • restructured the user guides around all v1 APIs
  • added guides for the newly introduced parts (compilations, bindings, and versioning utils)
  • added a few more examples, and a dedicated page for other projects already using Slang
  • added some clarifications to the guides about error tolerance and how we handle it
  • moved the guide examples under each guide, to make it easier to edit/review them
  • removed the (hidden/disabled) Rust examples, and replaced them with TypeScript ones
  • fixed a minor bug where QueryMatch root cursor was not exposed via WIT
  • relaxed the noUncheckedIndexedAccess tsconfig check, since it was adding more noise pollution to the examples than it is useful (cc @mjoerussell as you mentioned this before)

@OmarTawfik OmarTawfik requested review from a team as code owners February 26, 2025 17:01
@changeset-bot changeset-bot
Copy link

changeset-bot bot commented Feb 26, 2025 •
edited
Loading

🦋 Changeset detected

Latest commit: bedda10

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@nomicfoundation/slang Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@fzeoli
Copy link
Member

fzeoli commented Feb 26, 2025

Looks good! I think it would be valuable to have, in addition to these, some short tutorials/examples around common workflows. Things like "producing a list of function names in a contract", or "finding all calls to a function". The information needed to understand how to do this is available within the guides in this PR, but if we could facilitate discovery by working from common user needs (what they will have in mind when they open the docs), then that would be a great easy entry point for new users to explore Slang quickly. Those shorter examples should link to the longer doc pieces that go more in depth about the things being used

ggiraldez
ggiraldez reviewed Feb 27, 2025
View reviewed changes
Copy link
Contributor

@ggiraldez ggiraldez left a comment

Choose a reason for hiding this comment

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

Left some suggestions.

stefanoban
stefanoban reviewed Feb 28, 2025
View reviewed changes
Copy link
Contributor

@stefanoban stefanoban left a comment

Choose a reason for hiding this comment

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

Thank you, Omar! Looks great! I left a couple questions / suggestions.

beta-ziliani
beta-ziliani reviewed Mar 5, 2025
View reviewed changes
Copy link
Contributor

@beta-ziliani beta-ziliani left a comment

Choose a reason for hiding this comment

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

Just a few little comments. This is gold!

OmarTawfik
OmarTawfik commented Mar 6, 2025
View reviewed changes
ggiraldez
ggiraldez approved these changes Mar 6, 2025
View reviewed changes
Copy link
Contributor

@ggiraldez ggiraldez left a comment

Choose a reason for hiding this comment

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

Left a couple of non-blocking comments, but otherwise looks good!

@ggiraldez ggiraldez mentioned this pull request Mar 7, 2025
Closed
@OmarTawfik OmarTawfik enabled auto-merge March 7, 2025 13:43
OmarTawfik and others added 3 commits March 7, 2025 05:44
@OmarTawfik
revamp user guides
98c97f7 
- restructured the user guides around all v1 APIs
- added guides for the newly introduced parts (compilations, bindings, and versioning utils)
- added a few more examples, and a dedicated page for other projects already using Slang
- removed the (hidden/disabled) Rust examples, and replaced them with TypeScript ones
- fixed a minor bug where `QueryMatch` root cursor was not exposed via WIT
- added some clarifications to the guides about error tolerance and how we handle it
- relaxed the `noUncheckedIndexedAccess` tsconfig check, since it was adding more noise pollution to the examples than it is useful
- moved the guide examples under each guide, to make it easier to edit/review them

NOTE:

This is missing 3 examples for binding graph/builtins, that I'm adding right now. They are currently disabled with `TODO` comments. But creating the PR now since it is a large change, and it would be good to start getting feedback.
@ggiraldez @OmarTawfik
Add user guide examples for bindings graph and Solidity built-ins
228e2e4
@ggiraldez @OmarTawfik
Rewrite examples and section for binding graph user guide
0dd9d0f
@OmarTawfik OmarTawfik added this pull request to the merge queue Mar 7, 2025
@OmarTawfik OmarTawfik removed this pull request from the merge queue due to a manual request Mar 7, 2025
@OmarTawfik OmarTawfik enabled auto-merge March 7, 2025 13:45
@OmarTawfik OmarTawfik added this pull request to the merge queue Mar 7, 2025
Merged via the queue into main with commit 9f5d8f0 Mar 7, 2025
4 checks passed
@OmarTawfik OmarTawfik deleted the user-guides branch March 7, 2025 14:34
@github-actions github-actions bot mentioned this pull request Mar 7, 2025
Closed
beta-ziliani
beta-ziliani approved these changes Mar 7, 2025
View reviewed changes
Copy link
Contributor

@beta-ziliani beta-ziliani left a comment

Choose a reason for hiding this comment

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

I added some minor improvements, like links to grammar and small English issues.

@OmarTawfik OmarTawfik mentioned this pull request Mar 7, 2025
Merged
@ggiraldez ggiraldez mentioned this pull request Mar 7, 2025
Merged
@github-actions github-actions bot mentioned this pull request Mar 7, 2025
Merged
github-merge-queue bot pushed a commit that referenced this pull request Mar 7, 2025
@ggiraldez
Add standalone examples to the user guides (#1269)
011f307 
Resubmitting this since #1267 was closed when #1257 was merged.

Adds a section with standalone examples to the user guide. These
examples demonstrate almost all the Slang APIs.
github-merge-queue bot pushed a commit that referenced this pull request Mar 10, 2025
@github-actions
Bump Slang Version (#1270)
a173a6c 
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and publish to npm
yourself or [setup this action to publish
automatically](https://github.com/changesets/action#with-publishing). If
you're not ready to do a release yet, that's fine, whenever you add more
changesets to main, this PR will be updated.


# Releases
## @nomicfoundation/slang@0.20.0

### Minor Changes

- [#1203](#1203)
[`a5c3b1a`](a5c3b1a)
Thanks [@ggiraldez](https://github.com/ggiraldez)! - add separate
contexts (ie. binding scopes) for Solidity and Yul built-ins

- [#1257](#1257)
[`9f5d8f0`](9f5d8f0)
Thanks [@OmarTawfik](https://github.com/OmarTawfik)! - export
`assertUserFileLocation()` and `assertBuiltInLocation()` utilities from
the `bindings` module

- [#1243](#1243)
[`99d182f`](99d182f)
Thanks [@ggiraldez](https://github.com/ggiraldez)! - add
`definition.references()` API to find all references that resolve to a
definition.

- [#1205](#1205)
[`103b331`](103b331)
Thanks [@mjoerussell](https://github.com/mjoerussell)! - Make
`Edge::label` a required field instead of being optional.

- [#1257](#1257)
[`9f5d8f0`](9f5d8f0)
Thanks [@OmarTawfik](https://github.com/OmarTawfik)! - update user
guides with new binding graph and compilation APIs

- [#1257](#1257)
[`9f5d8f0`](9f5d8f0)
Thanks [@OmarTawfik](https://github.com/OmarTawfik)! - export
`assertNonterminalNode()` and `assertTerminalNode()` utilities from the
`cst` module

### Patch Changes

- [#1246](#1246)
[`aea2dd0`](aea2dd0)
Thanks [@OmarTawfik](https://github.com/OmarTawfik)! - unreserve `jump`
and `jumpi` yul keywords between `0.6.0` and `0.8.0`

- [#1203](#1203)
[`a5c3b1a`](a5c3b1a)
Thanks [@ggiraldez](https://github.com/ggiraldez)! - enable `address
payable` from 0.5.0 and remove `transfer` built-in from non-payable
`address`es

- [#1246](#1246)
[`aea2dd0`](aea2dd0)
Thanks [@OmarTawfik](https://github.com/OmarTawfik)! - make sure
assembly flags are only enabled starting from `0.8.13`

- [#1246](#1246)
[`aea2dd0`](aea2dd0)
Thanks [@OmarTawfik](https://github.com/OmarTawfik)! - enable yul's
`true` and `false` keywords starting from `0.6.2`

- [#1246](#1246)
[`aea2dd0`](aea2dd0)
Thanks [@OmarTawfik](https://github.com/OmarTawfik)! - make sure `super`
and `this` keywords are unreserved before `0.8.0`.

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
OmarTawfik added a commit to OmarTawfik-forks/slang that referenced this pull request Mar 11, 2025
@OmarTawfik
documentation fixes
63621bb 
- apply remaining suggestions from NomicFoundation#1257
- add grammar links to any remaining node names in user guides
- change query hilighting language to `smalltalk` as it is more readable
@OmarTawfik OmarTawfik mentioned this pull request Mar 11, 2025
Merged
github-merge-queue bot pushed a commit that referenced this pull request Mar 11, 2025
@OmarTawfik
documentation fixes (#1277)
b8a5e0e 
- apply remaining suggestions from #1257
- add grammar links to any remaining node names in user guides
- change query hilighting language to `smalltalk` as it is more readable
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ggiraldez ggiraldez ggiraldez approved these changes

@beta-ziliani beta-ziliani beta-ziliani approved these changes

+1 more reviewer

@stefanoban stefanoban stefanoban approved these changes

Reviewers whose approvals may not affect merge requirements
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
6 participants
@OmarTawfik @fzeoli @ggiraldez @beta-ziliani @stefanoban @mjoerussell