Skip to content
This repository was archived by the owner on Mar 19, 2021. It is now read-only.

Commit 3a7450a

Browse files
authored
[docs] Reorganize information on utility scripts (#18296)
The project's top-level README.md file contains a good deal of information which may not be relevant to all readers. This risks overwhelming newcomers, and it also discourages referencing the content in more targeted contexts from the project's documentation website. Move the information on command-line utility scripts from the top-level README.md file to a dedicated document within the docs/ directory.
1 parent aadbc0f commit 3a7450a

File tree

3 files changed

+26
-30
lines changed

3 files changed

+26
-30
lines changed

README.md

Lines changed: 0 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -339,36 +339,6 @@ For more details, see the [lint-tool documentation][lint-tool].
339339

340340
[lint-tool]: https://web-platform-tests.org/writing-tests/lint-tool.html
341341

342-
Adding command-line scripts ("tools" subdirs)
343-
---------------------------------------------
344-
345-
Sometimes you may want to add a script to the repository that's meant
346-
to be used from the command line, not from a browser (e.g., a script
347-
for generating test files). If you want to ensure (e.g., for security
348-
reasons) that such scripts won't be handled by the HTTP server, but
349-
will instead only be usable from the command line, then place them in
350-
either:
351-
352-
* the `tools` subdir at the root of the repository, or
353-
354-
* the `tools` subdir at the root of any top-level directory in the
355-
repository which contains the tests the script is meant to be used
356-
with
357-
358-
Any files in those `tools` directories won't be handled by the HTTP
359-
server; instead the server will return a 404 if a user navigates to
360-
the URL for a file within them.
361-
362-
If you want to add a script for use with a particular set of tests but
363-
there isn't yet any `tools` subdir at the root of a top-level
364-
directory in the repository containing those tests, you can create a
365-
`tools` subdir at the root of that top-level directory and place your
366-
scripts there.
367-
368-
For example, if you wanted to add a script for use with tests in the
369-
`notifications` directory, create the `notifications/tools` subdir and
370-
put your script there.
371-
372342
Test Review
373343
===========
374344

docs/writing-tests/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ There's also a load of [general guidelines](general-guidelines) that apply to al
2626
testdriver
2727
testdriver-tutorial
2828
testharness
29+
tools
2930
visual
3031
wdspec
3132
```

docs/writing-tests/tools.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Command-line utility scripts
2+
3+
Sometimes you may want to add a script to the repository that's meant to be
4+
used from the command line, not from a browser (e.g., a script for generating
5+
test files). If you want to ensure (e.g., for security reasons) that such
6+
scripts won't be handled by the HTTP server, but will instead only be usable
7+
from the command line, then place them in either:
8+
9+
* the `tools` subdir at the root of the repository, or
10+
11+
* the `tools` subdir at the root of any top-level directory in the repository
12+
which contains the tests the script is meant to be used with
13+
14+
Any files in those `tools` directories won't be handled by the HTTP server;
15+
instead the server will return a 404 if a user navigates to the URL for a file
16+
within them.
17+
18+
If you want to add a script for use with a particular set of tests but there
19+
isn't yet any `tools` subdir at the root of a top-level directory in the
20+
repository containing those tests, you can create a `tools` subdir at the root
21+
of that top-level directory and place your scripts there.
22+
23+
For example, if you wanted to add a script for use with tests in the
24+
`notifications` directory, create the `notifications/tools` subdir and put your
25+
script there.

0 commit comments

Comments
 (0)