Initial SCOOBE Spec added

[dedavis6797]

Summary of the Pull Request

What is this about:
Publishing the functional spec for update dialogs, aka second chance out of box experience (SCOOBE), which highlight noteworthy additions and improvements to PowerToys.

What is include in the PR:
SCOOBE Spec for public review/feedback

To view draft: click here

Tracking issue: #10979

How does someone test / validate:
N/A

Contributor License Agreement (CLA)

A CLA must be signed. If not, go over here and sign the CLA.

[htcfreek]

Question.

[htcfreek]

Any plans to caching the data for the case that no network is available when the user reopens the oobe section?

[crutkas]

good call out

[enricogior]

This point also applies to OOBE, but as explained in previous comment, it's important to keep them in sync. The ability to update just SCOOBE is bring little to no benefits to the users, but brings more complexity for development and testing and opens the door to inconsistencies with OOBE.

[Aaron-Junker]

I think that can be achieved by adding images of the new features and links like "try it out"

[Aaron-Junker]

I would localize keystrokes not until #9482 is implemented

[enricogior]

The problem is here is not just how to localize content like keystrokes, the problem is the added complexity to the entire localization process and the fact that SCOOBE needs to implement its own logic to determine what locale should be used, adding another layer of complexity for both development and testing.

Specifications for the entire localization process and specification for how SCOOBE should programmatically manage localized resources must be fully specified.

[Aaron-Junker]

The best would be the keys styled like real keys.

Like the example from w3schools:

Link

[Aaron-Junker]

Do we have telemetry data on how many users are using version ... . If so we should look at that for this decision

[htcfreek]

More interesting here are the telemetry data of update path like from 0.33 directly to 0.37.
@dedavis6797, is this covered by telemetry?

[Aaron-Junker]

Suggested change

	|10. | The user should be able to choose in the settings if he wants to see the SCOOBE dialog after the next time PowerToys updates| P2 |

[enricogior]

This opens the door to inconsistencies between OOBE and SCOOBE.
OOBE and SCOOBE should use the same content location otherwise the work to keep them in sync becomes a nightmare.

[enricogior]

This is also something that should be discussed because it makes the implementation and testing overwhelming for our team that is too small to keep adding features that provide little benefit to the users but are a potential source of bugs and add complexity to the development and testing phases.
For the end user, the fact that the content is dynamic is irrelevant and actually a potential limitation.
What is the real motivation to want dynamic content that needs to be downloaded from the internet?
Why do we need the ability to update that content after a new version has been released?
If we open SCOOBE as soon as the new version is executed, the users will see it at that time and then dismiss it.
Changing that content afterward will result in not being seen by the users that have already checked SCOOBE.
Adding a notification mechanism to alert those users that SCOOBE has been updated is another of those things that the team can't afford to do.

[enricogior]

This is another feature that will require a significant amount of testing and could be a potential source of bugs bringing very little benefit to the users and also limit those users that are regularly updating but might skip checking SCOOBE for some releases, but that would still like to reopen SCOOBE at a later time to check previous updates to see the new features.

Showing a version-to-version list of updates would cover all the scenarios and not have any limitation in terms of information provided.

[enricogior]

Given my previous comment this would become irrelevant.

[enricogior]

This is a show stopped and unless there is a full specification, it is pointless to even consider starting the SCOOBE development.

[enricogior]

Not sure what are the implication of this requirement.
What is the date/time of the upgrade? How is this relevant given SCOOBE is shown when PowerToys is first run after the upgrade?

[enricogior]

This is also very unclear. If SCOOBE is shown when the new version is executed for the first time, how could this result in a value that is not 100%?

[enricogior]

It is unclear what this is, since the content is dynamic, how would SCOOBE detect that the user has clicked on link to the settings page for a particular module?
This requires a full specification.

[enricogior]

Same as for the previous point. This needs a full specification.

[enricogior]

This screen size information is already available as part of the system telemetry.

[github-actions]

@check-spelling-bot Report

Unrecognized words, please review:

• onboarding

Previously acknowledged words that are now absent

apos bc bh Chris's classmethod cls cn cx cz deque df dw EB ev fd fody fx getmembers gh hc hh hk hu ip ismethod jp Kf lambson laute loadingbar messagebox multithreading nonwin NX overlaywindow pb Pn pv pw px QI rpc ru rv rx Shortcutguide sz tadele td tt tw Tz ul uv vh vk vm vw Vx wostringstream xa XY yy Zc zh zipfolder zm

To accept these unrecognized words as correct (and remove the previously acknowledged and now absent words), run the following commands

... in a clone of the [email protected]:microsoft/PowerToys.git repository
on the users/dedavis/SCOOBE_Spec branch:

update_files() {
perl -e '
my @expect_files=qw('".github/actions/spell-check/expect.txt"');
@ARGV=@expect_files;
my @stale=qw('"$patch_remove"');
my $re=join "|", @stale;
my $suffix=".".time();
my $previous="";
sub maybe_unlink { unlink($_[0]) if $_[0]; }
while (<>) {
if ($ARGV ne $old_argv) { maybe_unlink($previous); $previous="$ARGV$suffix"; rename($ARGV, $previous); open(ARGV_OUT, ">$ARGV"); select(ARGV_OUT); $old_argv = $ARGV; }
next if /^(?:$re)(?:(?:\r|\n)*$| .*)/; print;
}; maybe_unlink($previous);'
perl -e '
my $new_expect_file=".github/actions/spell-check/expect.txt";
use File::Path qw(make_path);
use File::Basename qw(dirname);
make_path (dirname($new_expect_file));
open FILE, q{<}, $new_expect_file; chomp(my @words = <FILE>); close FILE;
my @add=qw('"$patch_add"');
my %items; @items{@words} = @words x (1); @items{@add} = @add x (1);
@words = sort {lc($a)."-".$a cmp lc($b)."-".$b} keys %items;
open FILE, q{>}, $new_expect_file; for my $word (@words) { print FILE "$word\n" if $word =~ /\w/; };
close FILE;
system("git", "add", $new_expect_file);
'
}

comment_json=$(mktemp)
curl -L -s -S \
  --header "Content-Type: application/json" \
  "https://api.github.com/repos/microsoft/PowerToys/issues/comments/845246893" > "$comment_json"
comment_body=$(mktemp)
jq -r .body < "$comment_json" > $comment_body
rm $comment_json

patch_remove=$(perl -ne 'next unless s{^</summary>(.*)</details>$}{$1}; print' < "$comment_body")
  

patch_add=$(perl -e '$/=undef;
$_=<>;
s{<details>.*}{}s;
s{^#.*}{};
s{\n##.*}{};
s{(?:^|\n)\s*\*}{}g;
s{\s+}{ }g;
print' < "$comment_body")
  
update_files
rm $comment_body
git add -u

If you see a bunch of garbage

If it relates to a ...

well-formed pattern

See if there's a pattern that would match it.

If not, try writing one and adding it to the patterns.txt file.

Patterns are Perl 5 Regular Expressions - you can test yours before committing to verify it will match your lines.

Note that patterns can't match multiline strings.

binary-ish string

Please add a file path to the excludes.txt file instead of just accepting the garbage.

File paths are Perl 5 Regular Expressions - you can test yours before committing to verify it will match your files.

^ refers to the file's path from the root of the repository, so ^README\.md$ would exclude README.md (on whichever branch you're using).

[github-actions]

@check-spelling-bot Report

Unrecognized words, please review:

• onboarding

Previously acknowledged words that are now absent

apos bc bh Chris's classmethod cls cn cx cz deque df dw EB ev fd fody fx getmembers gh hc hh hk hu ip ismethod jp Kf lambson laute loadingbar messagebox multithreading nonwin NX overlaywindow pb Pn pv pw px QI rpc ru rv rx Shortcutguide sz tadele td tt tw Tz ul uv vh vk vm vw Vx wostringstream xa XY yy Zc zh zipfolder zm

To accept these unrecognized words as correct (and remove the previously acknowledged and now absent words), run the following commands

... in a clone of the [email protected]:microsoft/PowerToys.git repository
on the users/dedavis/SCOOBE_Spec branch:

update_files() {
perl -e '
my @expect_files=qw('".github/actions/spell-check/expect.txt"');
@ARGV=@expect_files;
my @stale=qw('"$patch_remove"');
my $re=join "|", @stale;
my $suffix=".".time();
my $previous="";
sub maybe_unlink { unlink($_[0]) if $_[0]; }
while (<>) {
if ($ARGV ne $old_argv) { maybe_unlink($previous); $previous="$ARGV$suffix"; rename($ARGV, $previous); open(ARGV_OUT, ">$ARGV"); select(ARGV_OUT); $old_argv = $ARGV; }
next if /^(?:$re)(?:(?:\r|\n)*$| .*)/; print;
}; maybe_unlink($previous);'
perl -e '
my $new_expect_file=".github/actions/spell-check/expect.txt";
use File::Path qw(make_path);
use File::Basename qw(dirname);
make_path (dirname($new_expect_file));
open FILE, q{<}, $new_expect_file; chomp(my @words = <FILE>); close FILE;
my @add=qw('"$patch_add"');
my %items; @items{@words} = @words x (1); @items{@add} = @add x (1);
@words = sort {lc($a)."-".$a cmp lc($b)."-".$b} keys %items;
open FILE, q{>}, $new_expect_file; for my $word (@words) { print FILE "$word\n" if $word =~ /\w/; };
close FILE;
system("git", "add", $new_expect_file);
'
}

comment_json=$(mktemp)
curl -L -s -S \
  --header "Content-Type: application/json" \
  "https://api.github.com/repos/microsoft/PowerToys/issues/comments/845309208" > "$comment_json"
comment_body=$(mktemp)
jq -r .body < "$comment_json" > $comment_body
rm $comment_json

patch_remove=$(perl -ne 'next unless s{^</summary>(.*)</details>$}{$1}; print' < "$comment_body")
  

patch_add=$(perl -e '$/=undef;
$_=<>;
s{<details>.*}{}s;
s{^#.*}{};
s{\n##.*}{};
s{(?:^|\n)\s*\*}{}g;
s{\s+}{ }g;
print' < "$comment_body")
  
update_files
rm $comment_body
git add -u

If you see a bunch of garbage

If it relates to a ...

well-formed pattern

See if there's a pattern that would match it.

If not, try writing one and adding it to the patterns.txt file.

Patterns are Perl 5 Regular Expressions - you can test yours before committing to verify it will match your lines.

Note that patterns can't match multiline strings.

binary-ish string

Please add a file path to the excludes.txt file instead of just accepting the garbage.

File paths are Perl 5 Regular Expressions - you can test yours before committing to verify it will match your files.

^ refers to the file's path from the root of the repository, so ^README\.md$ would exclude README.md (on whichever branch you're using).

[enricogior]

@dedavis6797
LGTM!

[crutkas]

@dedavis6797 what needs to be done here

[crutkas]

@dedavis6797 what needs to be done here

[github-actions]

@check-spelling-bot Report

Unrecognized words, please review:

• onboarding

Previously acknowledged words that are now absent

apos bc bh Chris's classmethod cls cn cx cz deque df dw EB ev fd fody fx getmembers gh hc hh hk hu ip ismethod jp Kf lambson laute loadingbar messagebox multithreading nonwin NX overlaywindow pb Pn pv pw px QI rpc ru rv rx Shortcutguide sz tadele td tt tw Tz ul uv vh vk vm vw Vx wostringstream xa XY yy Zc zh zipfolder zm

To accept these unrecognized words as correct (and remove the previously acknowledged and now absent words), run the following commands

... in a clone of the [email protected]:microsoft/PowerToys.git repository
on the users/dedavis/SCOOBE_Spec branch:

update_files() {
perl -e '
my @expect_files=qw('".github/actions/spell-check/expect.txt"');
@ARGV=@expect_files;
my @stale=qw('"$patch_remove"');
my $re=join "|", @stale;
my $suffix=".".time();
my $previous="";
sub maybe_unlink { unlink($_[0]) if $_[0]; }
while (<>) {
if ($ARGV ne $old_argv) { maybe_unlink($previous); $previous="$ARGV$suffix"; rename($ARGV, $previous); open(ARGV_OUT, ">$ARGV"); select(ARGV_OUT); $old_argv = $ARGV; }
next if /^(?:$re)(?:(?:\r|\n)*$| .*)/; print;
}; maybe_unlink($previous);'
perl -e '
my $new_expect_file=".github/actions/spell-check/expect.txt";
use File::Path qw(make_path);
use File::Basename qw(dirname);
make_path (dirname($new_expect_file));
open FILE, q{<}, $new_expect_file; chomp(my @words = <FILE>); close FILE;
my @add=qw('"$patch_add"');
my %items; @items{@words} = @words x (1); @items{@add} = @add x (1);
@words = sort {lc($a)."-".$a cmp lc($b)."-".$b} keys %items;
open FILE, q{>}, $new_expect_file; for my $word (@words) { print FILE "$word\n" if $word =~ /\w/; };
close FILE;
system("git", "add", $new_expect_file);
'
}

comment_json=$(mktemp)
curl -L -s -S \
  --header "Content-Type: application/json" \
  "https://api.github.com/repos/microsoft/PowerToys/issues/comments/916264332" > "$comment_json"
comment_body=$(mktemp)
jq -r .body < "$comment_json" > $comment_body
rm $comment_json

patch_remove=$(perl -ne 'next unless s{^</summary>(.*)</details>$}{$1}; print' < "$comment_body")
  

patch_add=$(perl -e '$/=undef;
$_=<>;
s{<details>.*}{}s;
s{^#.*}{};
s{\n##.*}{};
s{(?:^|\n)\s*\*}{}g;
s{\s+}{ }g;
print' < "$comment_body")
  
update_files
rm $comment_body
git add -u

If you see a bunch of garbage

If it relates to a ...

well-formed pattern

See if there's a pattern that would match it.

If not, try writing one and adding it to the patterns.txt file.

Patterns are Perl 5 Regular Expressions - you can test yours before committing to verify it will match your lines.

Note that patterns can't match multiline strings.

binary-ish string

Please add a file path to the excludes.txt file instead of just accepting the garbage.

File paths are Perl 5 Regular Expressions - you can test yours before committing to verify it will match your files.

^ refers to the file's path from the root of the repository, so ^README\.md$ would exclude README.md (on whichever branch you're using).