feat: add full Zonemaster stack with Docker and Spanish UI
- Clone all 5 Zonemaster component repos (LDNS, Engine, CLI, Backend, GUI) - Dockerfile.backend: 8-stage multi-stage build LDNS→Engine→CLI→Backend - Dockerfile.gui: Astro static build served via nginx - docker-compose.yml: backend (internal) + frontend (port 5353) - nginx.conf: root redirects to /es/, /api/ proxied to backend - zonemaster-gui/config.ts: defaultLanguage set to 'es' (Spanish) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
71
zonemaster-engine/docs/Implementing_Tests.pod
Normal file
71
zonemaster-engine/docs/Implementing_Tests.pod
Normal file
@@ -0,0 +1,71 @@
|
||||
=head1 INTRODUCTION
|
||||
|
||||
The Zonemaster system intends to provide a framework for implementing DNS tests. In order to do this, it exposes APIs to the test code for examining a
|
||||
DNS zone, to emit examination results and to access configuration information on how the tests should be performed.
|
||||
|
||||
=head1 RULES AND RECOMMENDATIONS FOR TEST CODE
|
||||
|
||||
=over
|
||||
|
||||
=item Only access the outside world via the framework APIs.
|
||||
|
||||
The framework is built to make test results traceable, repeatable and understandable. If the test code itself goes around the framework and accesses
|
||||
things on its own, all those attributes are lost. If the test you're writing needs something the framework doesn't provide, request that it be added
|
||||
to the framework.
|
||||
|
||||
=item Make as few assumptions as possible.
|
||||
|
||||
When the entry method in a test module is called, it can only rely on a handful of things about the testing process so far:
|
||||
|
||||
=over
|
||||
|
||||
=item
|
||||
|
||||
The zone object it's given has a parent.
|
||||
|
||||
=item
|
||||
|
||||
The zone object it's given has glue records.
|
||||
|
||||
=item
|
||||
|
||||
The zone object it's given has nameservers.
|
||||
|
||||
=back
|
||||
|
||||
=item Favor code clarity over performance.
|
||||
|
||||
Strive to make the test code as easily understandable as possible. Ideally, it should be possible for a person with only a basic understanding of Perl to
|
||||
read the code and verify that it correctly implements the corresponding Test Case specifications.
|
||||
|
||||
=back
|
||||
|
||||
=head1 TEST MODULE STRUCTURE
|
||||
|
||||
The Zonemaster framework will attempt to load and call all modules in the namespace C<Zonemaster::Engine::Test>. These modules must have three class methods
|
||||
defined. One to run all tests it provides, and two to expose metadata about the module. Apart from that (and the rules above) the module can be
|
||||
implemented as desired.
|
||||
|
||||
=head2 Metadata methods
|
||||
|
||||
=over
|
||||
|
||||
=item C<version()>
|
||||
|
||||
This method should return a string representing the current version of the test module. The version information will be logged in a C<SYSTEM>
|
||||
message, but otherwise not used.
|
||||
|
||||
=item C<metadata()>
|
||||
|
||||
This method should return a reference to a hash. The keys of this hash should be the names of the individual test methods in the module, and the
|
||||
values for each key should be a reference to an array listing all the possible messages that test methods can emit.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Test-running method(s)
|
||||
|
||||
The framework expects to be able to run all tests in a module by calling a class method L<all()|Zonemaster::Engine::Test/all()> with a
|
||||
L<Zonemaster::Engine::Zone> object as the argument.
|
||||
The return value from this method is expected to be a list of L<Zonemaster::Engine::Logger::Entry> objects describing the results of the tests run.
|
||||
|
||||
=cut
|
||||
63
zonemaster-engine/docs/Translation.pod
Normal file
63
zonemaster-engine/docs/Translation.pod
Normal file
@@ -0,0 +1,63 @@
|
||||
=head1 TRANSLATION
|
||||
|
||||
=head2 Introduction
|
||||
|
||||
The translation system in Zonemaster is a two-step process, where internal
|
||||
message tags are first replaced by English strings with argument
|
||||
placeholders, and a second step where GNU gettext is used to translate the
|
||||
strings to other languages and fill in the placeholders based on provided data.
|
||||
|
||||
All translation files live in the F<share> directory in the
|
||||
L<Zonemaster::Engine> source directory and all commands described here are
|
||||
executed from that directory.
|
||||
|
||||
=head2 For translators
|
||||
|
||||
Instructions for translators can be found at
|
||||
L<https://github.com/zonemaster/zonemaster/blob/develop/docs/internal/maintenance/Instructions-for-translators.md>
|
||||
|
||||
=head2 For developers of Zonemaster test modules
|
||||
|
||||
The test module code should produce log messages with message tags, as documented
|
||||
elsewhere. These tags will be used for translation to human language, for
|
||||
determining the severity of the event logged and to make the events easily used
|
||||
by other software.
|
||||
|
||||
Each test module must also have a method named C<tag_descriptions()>.
|
||||
This method must return a reference to a hash whose entries are expected to look
|
||||
like this, where C<MESSAGE_TAG> is a message, C<TEST_MODULE> is the name of a
|
||||
test module tag and C<"Hello, {name}!"> is a message id:
|
||||
|
||||
MESSAGE_TAG => sub {
|
||||
__x # TEST_MODULE:MESSAGE_TAG
|
||||
"Hello, {name}!", @_;
|
||||
},
|
||||
|
||||
A number of things are important here.
|
||||
Keys in the hashref are message tags and values are coderefs.
|
||||
The coderef calls Locale::TextDomain::__x() with a Perl brace format string
|
||||
(a.k.a. message id) and passes along its own @_).
|
||||
The coderef propagates the return value of Locale::TextDomain::__x().
|
||||
The line immediately before the format string contains a comment consisting of
|
||||
the module name, a colon and the message tag.
|
||||
|
||||
The format strings themselves, the comments and the line numbers of the __x
|
||||
calls are used by the gettext tooling when updating the PO files with new
|
||||
message ids and old message strings.
|
||||
|
||||
=head2 For Zonemaster package maintainers
|
||||
|
||||
In order to make a new translation usable, it must be compiled to C<mo> format
|
||||
and installed. The first step needs the C<msgfmt> program from the GNU gettext
|
||||
package to be installed and available in the shell path. As long as it is, it
|
||||
should be enough to go to the F<share> directory and run C<make>.
|
||||
This is automatically done when following the release instructions.
|
||||
|
||||
For the new translation to actually be installed, the C<mo> file must be added
|
||||
to the F<MANIFEST> file. At the end of the C<make> run, it should have printed
|
||||
a list of all the paths that has to be there. Just open F<MANIFEST> in a text
|
||||
editor, check that all the lines are in there and add any that are missing (if
|
||||
you just added a new translation, that will be missing, for example).
|
||||
|
||||
Once the new translation is compiled and added to F<MANIFEST>, the normal Perl
|
||||
C<make install> process will install it.
|
||||
Reference in New Issue
Block a user