Perl 6
Smart Linking: Revision 4
Smart Links refer to a special syntax used in the test suite which connect a particular part of a test script with a specific part of the Perl 6 specification.
^^ Smart Links Example
A smart link looks like this in a test script:
.pre
# L<S29/Math::Trig>
.pre
After submitting this to the Subversion repository, after a few minutes a cron script will update a copy of the Specification which references these links. See the "Math::Trig spec"<http://feather.perl6.nl/syn/S29.html#Math%3A%3ATrig> for an example.
^^ Benefits of Smart Links
Smart links are especially valuable for a language that is in development. The help answer these important questions:
* *Has this feature been tested?* If you don't see references to tests from the spec, there's a possibility the feature is not only untested, but unimplemented!
* *Are there duplicates tests for this feature?* If you see more than one test script linked in one place, it's possible there are duplicate tests, and the tests suite can be simplified.
* *Is there a spec for this feature?* On the other hand, if you find a test _without_ a smart link, it may simply not have one yet, or the feature may be unspec'ed. It was discovered that the basic function "say" did not have a formal definition through this kind of review.
^^ Smart Linking Status
As of September 11th, 2006, 263 test scripts have at least one smart link, but 349 do not.
Help wanted!
^^ How to help with smart linking.
To help with this, you mostly just some motivation to help, and commit access
to the pugs tree. Ask for it on #perl6 if you don't have it.
`perldoc util/smartlinks.pl` explains the details. Here are practical tips to get started.
1. Review the complete list of files with no smart links:
.pre
grep -RL 'L<' t/* | $PAGER
.pre
2. Pick a directory that needs work. For example, in builtins/lists, 11 files need updated now.
.pre
cd builtins/lists
.pre
3. Open these files
.pre
$EDITOR `grep -L 'L<' *.t`
.pre
4. Add at least one appropriate smart link, possibly using the "online specification"<http://feather.perl6.nl/syn> as a reference. The nice thing about working in one directory at one time, is that all of the smart links in the directory me be similar.
5. Check your smart links
.pre
~/pugs/util/smartlink.pl --check --fast *.t
.pre
Hopefully, you'll get some useful debugging feedback if there is a problem.
6. Commit your work!
Usually this is `svk commit` or `svn commit`.
Ask for help on the #perl6 IRC channel if you get stuck.
^^ Smart Links Example
A smart link looks like this in a test script:
.pre
# L<S29/Math::Trig>
.pre
After submitting this to the Subversion repository, after a few minutes a cron script will update a copy of the Specification which references these links. See the "Math::Trig spec"<http://feather.perl6.nl/syn/S29.html#Math%3A%3ATrig> for an example.
^^ Benefits of Smart Links
Smart links are especially valuable for a language that is in development. The help answer these important questions:
* *Has this feature been tested?* If you don't see references to tests from the spec, there's a possibility the feature is not only untested, but unimplemented!
* *Are there duplicates tests for this feature?* If you see more than one test script linked in one place, it's possible there are duplicate tests, and the tests suite can be simplified.
* *Is there a spec for this feature?* On the other hand, if you find a test _without_ a smart link, it may simply not have one yet, or the feature may be unspec'ed. It was discovered that the basic function "say" did not have a formal definition through this kind of review.
^^ Smart Linking Status
As of September 11th, 2006, 263 test scripts have at least one smart link, but 349 do not.
Help wanted!
^^ How to help with smart linking.
To help with this, you mostly just some motivation to help, and commit access
to the pugs tree. Ask for it on #perl6 if you don't have it.
`perldoc util/smartlinks.pl` explains the details. Here are practical tips to get started.
1. Review the complete list of files with no smart links:
.pre
grep -RL 'L<' t/* | $PAGER
.pre
2. Pick a directory that needs work. For example, in builtins/lists, 11 files need updated now.
.pre
cd builtins/lists
.pre
3. Open these files
.pre
$EDITOR `grep -L 'L<' *.t`
.pre
4. Add at least one appropriate smart link, possibly using the "online specification"<http://feather.perl6.nl/syn> as a reference. The nice thing about working in one directory at one time, is that all of the smart links in the directory me be similar.
5. Check your smart links
.pre
~/pugs/util/smartlink.pl --check --fast *.t
.pre
Hopefully, you'll get some useful debugging feedback if there is a problem.
6. Commit your work!
Usually this is `svk commit` or `svn commit`.
Ask for help on the #perl6 IRC channel if you get stuck.
