mirror of
https://github.com/GraphiteEditor/Graphite.git
synced 2026-09-15 14:18:04 +08:00
Add the build link bisect tool to the website (#3902)
* Add the bisect tool * Add `cargo run explore` to open bisect tool * Website cleanup * Bug fixes * Fix again
This commit is contained in:
Keavon Chambers
@@ -166,7 +166,7 @@ Adam is a pragmatic problem solver with a talent for simplifying complexity. He
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<div class="triptych">
|
||||
<div class="triptych" id="extras">
|
||||
|
||||
<div class="block">
|
||||
|
||||
|
||||
@@ -3,31 +3,103 @@ title = "Debugging tips"
|
||||
|
||||
[extra]
|
||||
order = 2 # Page number after chapter intro
|
||||
css = ["/page/contributor-guide/bisect-tool.css"]
|
||||
js = ["/js/page/contributor-guide/bisect-tool.js"]
|
||||
+++
|
||||
|
||||
The Wasm-based editor has some unique limitations about how you are able to debug it. This page offers tips and best practices to get the most out of your problem-solving efforts.
|
||||
|
||||
## Comparing with deployed builds
|
||||
|
||||
When tracking down a bug, first check if the issue you are noticing also exists in `master` or just in your branch. Open up [dev.graphite.art](https://dev.graphite.art) which always deploys the lastest commit, as opposed to [editor.graphite.art](https://editor.graphite.art) which deploys the latest stable release. Build links for any commit may be found by clicking the "comment" icon on the right side of any commit in the [GitHub repo commits list](https://github.com/GraphiteEditor/Graphite/commits/master/).
|
||||
When tracking down a bug, first check if the issue you are noticing also exists in `master` or just in your branch. Open up [dev.graphite.art](https://dev.graphite.art) which always deploys the lastest commit, as opposed to [editor.graphite.art](https://editor.graphite.art) which deploys the latest stable release. Build links for any commit may be found by clicking the "comment" icon on the right side of any commit in the GitHub repo [commits list](https://github.com/GraphiteEditor/Graphite/commits/master/).
|
||||
|
||||
Use *Help* > *About Graphite* in the editor to view any build's Git commit hash.
|
||||
Use *Help* > *About Graphite…* in the editor to view any build's Git commit hash.
|
||||
|
||||
Beware of one potential pitfall: all deploys and build links are built with release optimizations enabled. This means some bugs (like crashes from bounds checks or debug assertions) may exist in `master` and would appear if run locally, but not in the deployed version.
|
||||
Beware of a potential pitfall: all deploys and build links are built with release optimizations enabled. This means some bugs (like crashes from bounds checks or debug assertions) may exist in `master` and would appear if run locally, but not in the deployed version.
|
||||
|
||||
## Build bisect tool
|
||||
|
||||
```sh
|
||||
# Access this quickly in the future:
|
||||
cargo run explore bisect
|
||||
```
|
||||
|
||||
This interactive tool helps you binary search through recent commits, test the build links of each, and pinpoint which change introduced a regression or added a feature.
|
||||
|
||||
<div class="bisect-tool">
|
||||
|
||||
<div class="phase active" data-phase="setup">
|
||||
<div class="setup-section">
|
||||
<div class="section-label">
|
||||
<span><strong>What are you looking for?</strong></span>
|
||||
</div>
|
||||
<label>
|
||||
<input type="radio" name="bisect-mode" value="regression" checked />
|
||||
<span>Find when a regression or bug started</span>
|
||||
</label>
|
||||
<label>
|
||||
<input type="radio" name="bisect-mode" value="feature" />
|
||||
<span>Find when a feature was added or fixed</span>
|
||||
</label>
|
||||
</div>
|
||||
<div class="setup-section">
|
||||
<div class="section-label">
|
||||
<span><strong>When do you estimate this changed?</strong></span>
|
||||
</div>
|
||||
<label>
|
||||
<input type="radio" name="start-method" value="date" checked />
|
||||
<span>Date</span>
|
||||
</label>
|
||||
<label>
|
||||
<input type="radio" name="start-method" value="hash" />
|
||||
<span>Commit</span>
|
||||
</label>
|
||||
</div>
|
||||
<div class="commit-inputs">
|
||||
<div class="start-input" data-input="date">
|
||||
<input type="date" data-commit-date />
|
||||
</div>
|
||||
<div class="start-input hidden" data-input="hash">
|
||||
<input data-commit-hash placeholder="Commit hash" pattern="[0-9a-fA-F]{7,40}" />
|
||||
</div>
|
||||
<span class="button arrow" data-start-button>Begin bisect</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="phase" data-phase="bisect">
|
||||
<div class="block feature-box-narrow">
|
||||
<div class="step-header">
|
||||
<span class="step-label" data-step-label><strong>Bisect step 1</strong></span>
|
||||
<span class="go-back hidden" data-go-back-button>(<a>go back</a>)</span>
|
||||
</div>
|
||||
<div class="progress-info" data-progress-info></div>
|
||||
<div class="commit-info" data-commit-info></div>
|
||||
<span class="button arrow" data-test-build-button>Test this build</span>
|
||||
<span class="findings">After testing, what have you found?</span>
|
||||
<div class="bisect-actions">
|
||||
<span class="button" data-issue-present-button></span>
|
||||
<span class="button" data-issue-absent-button></span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="error-message" data-message-box></div>
|
||||
|
||||
</div>
|
||||
|
||||
## Printing to the console
|
||||
|
||||
Use the browser console (<kbd>F12</kbd>) to check for warnings and errors. Use the Rust macro `debug!("The number is {}", some_number);` to print to the browser console. These statements should be for temporary debugging. Remove them before your code is reviewed. Print-based debugging is necessary because breakpoints are not supported in WebAssembly.
|
||||
Use the browser console (<kbd>F12</kbd>) to check for warnings and errors. In Rust, use `log::debug!("The number is {some_number}");` to print to the browser console. These statements should be for temporary debugging. Remove them before your code is reviewed. Print-based debugging is necessary because breakpoints are not supported in WebAssembly.
|
||||
|
||||
Additional print statements are available that *should* be committed:
|
||||
|
||||
- `error!()` is for descriptive user-facing error messages arising from a bug
|
||||
- `warn!()` is for non-critical problems that likely indicate a bug somewhere
|
||||
- `trace!()` is for verbose logs of ordinary internal activity, hidden by default but viewable by activating *Help* > *Debug: Print Trace Logs*
|
||||
- `log::error!()` is for descriptive user-facing error messages arising from a bug
|
||||
- `log::warn!()` is for non-critical problems that likely indicate a bug somewhere
|
||||
- `log::trace!()` is for verbose logs of ordinary internal activity, hidden by default but viewable by activating *Help* > *Debug: Print Trace Logs*
|
||||
|
||||
## Message system logs
|
||||
|
||||
To also view logs of the messages dispatched by the message system, activate *Help* > *Debug: Print Messages* > *Only Names*. Or use *Full Contents* for a more verbose view containing the actual data being passed. This is an invaluable window into the activity of the message flow and works well together with `debug!()` printouts for tracking down message-related defects.
|
||||
To also view logs of the messages dispatched by the message system, activate *Help* > *Debug: Print Messages* > *Only Names*. Or use *Full Contents* for a more verbose view containing the actual data being passed. This is an invaluable window into the activity of the message flow and works well together with `log::debug!()` printouts for tracking down message-related defects.
|
||||
|
||||
## Node/layer and document IDs
|
||||
|
||||
|
||||
@@ -17,7 +17,12 @@ The dispatcher lives at the root of the editor hierarchy and acts as the owner o
|
||||
|
||||
## Editor outline
|
||||
|
||||
Click to explore the outline of the editor subsystem hierarchy which forms the structure of the editor's subsystems, state, and interactions. Bookmark this page to reference it later.
|
||||
```sh
|
||||
# Access this quickly in the future:
|
||||
cargo run explore editor
|
||||
```
|
||||
|
||||
Click to explore the outline of the editor subsystem hierarchy which forms the structure of the editor's subsystems, state, and interactions.
|
||||
|
||||
<div class="structure-outline">
|
||||
<!-- replacements::hierarchical_message_system_tree() -->
|
||||
|
||||
@@ -13,7 +13,7 @@ Please ensure Clippy is enabled. This should be set up automatically in VS Code.
|
||||
|
||||
## Naming
|
||||
|
||||
Please use descriptive variable/function/symbol names and keep abbreviations to a minimum. Prefer spelling out full words most of the time, so `gen_doc_fmt` should be written out as `generate_document_format` instead.
|
||||
Please use descriptive variable/function/symbol names and keep abbreviations to a minimum. Prefer spelling out full words most of the time, such as `generate_document_format` instead of `gen_doc_fmt`.
|
||||
|
||||
This avoids the mental burden of expanding abbreviations into semantic meaning. Monitors are wide enough to display long variable/function names, so descriptive is better than cryptic.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user