Skip to content
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.

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

[docs] Introduce tutorial on writing reftests #17811

Merged
merged 8 commits into from Aug 2, 2019

Conversation

@jugglinmike
Copy link
Contributor

jugglinmike commented Jul 12, 2019

Tutorials are a proven way of helping potential contributors orient
themselves quickly. By providing concrete instructions that are focused
on one specific task, projects can give readers a sense of the
contribution experience and offer a starting point for learning any
additional details that are relevant to their particular goals.

Replace existing content which demonstrates the contents of a reftest
with a complete narrative describing how and why such a test is
authored.


This was inspired by conversations with @fantasai, @frivoal, @lmccart, @ericholscher, @jihyerish, and @chrisdavidmills and the experience of the Django project maintainers.

Since this is more objective than any of the content we've considered so far (and since it's just a first draft), I especially welcome high-level design feedback. For example: is the <bdo> element a good motivating feature? Does this try to cover too much? Does it not cover enough?

I'm planning to write a similar tutorial for testharness.js tests and potentially still more tutorials after that. As that content comes together, I'd like to reference it from the documentation's landing page, but for now, I've limited integration to a couple places in the "writing tests" section.

Tutorials are a proven way of helping potential contributors orient
themselves quickly. By providing concrete instructions that are focused
on one specific task, projects can give readers a sense of the
contribution experience and offer a starting point for learning any
additional details that are relevant to their particular goals.

Replace existing content which demonstrates the contents of a reftest
with a complete narrative describing how and why such a test is
authored.
Copy link
Member

sideshowbarker left a comment

Beautiful

docs/writing-tests/reftest-tutorial.md Outdated Show resolved Hide resolved
docs/writing-tests/reftest-tutorial.md Outdated Show resolved Hide resolved
docs/writing-tests/reftest-tutorial.md Outdated Show resolved Hide resolved
docs/writing-tests/reftest-tutorial.md Outdated Show resolved Hide resolved
docs/writing-tests/reftests.md Show resolved Hide resolved
docs/writing-tests/reftest-tutorial.md Outdated Show resolved Hide resolved
@jugglinmike

This comment has been minimized.

Copy link
Contributor Author

jugglinmike commented Jul 17, 2019

@sideshowbarker I've made a few changes based on my experience writing another tutorial:

  • Avoid instructing the reader to actually create a pull request
  • Explain the design goal of conciseness over completeness as an HTML comment for future maintainers (this might go better in a dedicated document when/if both tutorials are accepted)
  • Add some suggestions for self-study
@jugglinmike

This comment has been minimized.

Copy link
Contributor Author

jugglinmike commented Aug 2, 2019

Thanks, @sideshowbarker! Thanks, @gsnedders! I'll do the honors myself

@jugglinmike jugglinmike merged commit ddc6346 into master Aug 2, 2019
9 of 11 checks passed
9 of 11 checks passed
website-build-and-publish website-build-and-publish
Details
manifest-build-and-tag manifest-build-and-tag
Details
Azure Pipelines Build #20190801.93 succeeded
Details
Azure Pipelines (./wpt test-jobs) ./wpt test-jobs succeeded
Details
Azure Pipelines (affected tests without changes: Safari Technology Preview) affected tests without changes: Safari Technology Preview succeeded
Details
Azure Pipelines (affected tests: Safari Technology Preview) affected tests: Safari Technology Preview succeeded
Details
Azure Pipelines (wpt.fyi hook: safari-preview-affected-tests) wpt.fyi hook: safari-preview-affected-tests succeeded
Details
Azure Pipelines (wpt.fyi hook: safari-preview-affected-tests-without-changes) wpt.fyi hook: safari-preview-affected-tests-without-changes succeeded
Details
Taskcluster (pull_request) TaskGroup: success
Details
staging.wpt.fyi - safari[experimental] Safari results
Details
wpt.fyi - safari[experimental] Safari results
Details
@gsnedders gsnedders deleted the docs-reftest-tutorial branch Aug 5, 2019
natechapin added a commit to natechapin/wpt that referenced this pull request Aug 23, 2019
Tutorials are a proven way of helping potential contributors orient
themselves quickly. By providing concrete instructions that are focused
on one specific task, projects can give readers a sense of the
contribution experience and offer a starting point for learning any
additional details that are relevant to their particular goals.

Replace existing content which demonstrates the contents of a reftest
with a complete narrative describing how and why such a test is
authored.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
4 participants
You can’t perform that action at this time.