Update sync documentation

[ErikSchierboom]

The current documentation for tests.toml files was still referring to the obsolete canonical data syncer. This PR updates the documentation to use configlet's sync command instead. It also updates the contents of the example tests.toml file to the latest spec.

Closes exercism/configlet#124

[ee7]

LGTM.

I did some nitpicking, partly unrelated to the canonical_data_syncer to configlet sync change - but is still in the scope of "update sync documentation"

And I've checked that, with this PR, running

$ git grep 'syncer'

in this repo produces no output.

[ee7]

Pinging @exercism/reviewers for a review.

This is an important docs update - the current wording has probably already caused a lot of confusion. Before this PR, the README for problem-specifications doesn't mention configlet (!).

[ErikSchierboom]

@SleeplessByte Care to review?

[ee7]

I'll update this PR to reflect the latest changes to configlet sync. A plain configlet sync is no longer interactive.

[ee7]

Done. I've also added some extra docs.

In the future, it would be nice if we didn't have to maintain 3 sets of configlet docs (in exercism/configlet, exercism/docs, and exercism/problem-specifications).

[ErikSchierboom]

Thanks! Ping @exercism/reviewers

[booniepepper]

Minor suggestions aside... lgtm

[ee7]

@hiljusti: Thanks for the review. You raise some good points about the wording, but it's a little tricky to find a great one.

Some things to consider:

1. A user can run a bash script on Windows, and when running on Windows, the fetch-configlet script correctly downloads the Windows release of configlet.
2. We might prefer to point Windows users towards the bash script because:
   1. The bash script is in every track repo, but the PowerShell script is only in 11 of 79 track repos. (The repos are: cpp, csharp, dart, fsharp, javascript, red, solidity, typescript, wren, z3, zig).
   2. Many Windows users are more familiar with bash than PowerShell.
   3. The bash script has been reviewed much more thoroughly than the PowerShell script.
3. A user can theoretically run a PowerShell script on a non-Windows OS. However, the fetch-configlet.ps1 always downloads the Windows release of configlet, so we should indeed communicate "only run the .ps1 script on Windows".
4. We currently only build configlet releases for Linux, macOS, and Windows (all x86_64 only).
5. The fetch-configlet script does run without error on the BSDs (as long as bash is installed). It downloads the Linux binary.
6. The Linux binary works fully on FreeBSD and NetBSD if Linux binary compatibility is enabled, as described e.g. here. However, I have not documented this fact, and we don't test it during CI. But I am willing to document it - I think it will stay working.
7. The Linux binary is statically linked, which makes it easier to run on the BSDs that provide Linux binary compatibility.
8. On BSDs that don't provide Linux binary compatibility (e.g. OpenBSD) a user who wants to use configlet must compile it themselves, or run a release binary in a VM.
9. I have tested that configlet compiles and runs properly on at least FreeBSD, OpenBSD, and NetBSD.

@ErikSchierboom any thoughts on the wording here?

Also: in the future, can we have a single source of truth for configlet installation instructions? If so, should that be in exercism/docs, or exercism/configlet? Then the instructions in exercism/problem-specifications can be minimal, and point elsewhere for more details.

[booniepepper]

All sounds reasonable to me

[ErikSchierboom]

Many Windows users are more familiar with bash than PowerShell.

In my experience, I've not found this to be true. Bash isn't even installed by default on Windows, so I don't think we can assume Windows users will just be able to run the Bash command.

Also: in the future, can we have a single source of truth for configlet installation instructions? If so, should that be in exercism/docs, or exercism/configlet? Then the instructions in exercism/problem-specifications can be minimal, and point elsewhere for more details.

I think having the documentation be in exercism/configlet and referring to that from the docs and prob-specs repos makes the most sense.

[booniepepper]

I'm fine with not further specifying OSs. It's kinda minor; I think Windows developers will recognize a .ps1 as a powershell script, and non-windows developers will ignore it because it's foreign. BSD developers are used to software (outside of ports) not working out-of-the-box

Rambly thoughts follow:

Since this targets track maintainers, I think it's less important what the OS image comes with and more important what developers will have installed. I'm not a Windows expert, though I do have one machine that runs it, and I even ran a Windows machine for a few weeks recently for work... though I just used it as a shell to reach other remote hosts I could use for development

Anyway - I know Bash won't be installed on Windows by default, but what is the developer setup these days for a Windows dev? Not all Linux distros will have git installed by default, but we expect people to have at least gotten that far if they're maintaining tracks. I thought the Cygwin/MinGW/GitBash days were mostly over since Windows Subsystem Linux 2.0 can be run as a (non-virtualized) peer to windows now. Not sure if that's what people are using, though. I've heard of some difficulties when you want to do deeper Linux networking things, since Windows can gate the Linux environment.

[ErikSchierboom]

Since this targets track maintainers, I think it's less important what the OS image comes with and more important what developers will have installed.

Correct, until we centralize the documentation in one place, in which case it will become aimed at students too.

Anyway - I know Bash won't be installed on Windows by default, but what is the developer setup these days for a Windows dev?

Unless you're running things exclusively in WSL, Windows users will probably have installed Git locally too. That means they'll have Git bash, but I never used in my 10+ years of running Git on Windows.

[SleeplessByte]

I use git bash all the time, but it's important to note that those bash scripts only work in a git bash environment, which you're not always in. I don't use WSL.

I would prefer keeping both the "cross-env-if-you're-bash-like" and "always-works-on-windows" scripts.

[ee7]

I mostly liked @hiljusti's other suggestion, I just wanted to:

• avoid the possible reading of "the bash script cannot be run on Windows"
• clarify that the PowerShell script is Windows-only

As a final thing before we merge this - how about this?

[ErikSchierboom]

Thanks everyone!