Skip to content

Latest commit

 

History

History
353 lines (290 loc) · 13.4 KB

CONTRIBUTING.md

File metadata and controls

353 lines (290 loc) · 13.4 KB
Raw

po4a welcomes contributions!

Even if you have never contributed to any Open Source project in the past, you are welcome: we are willing to help and mentor you here. Check on First Timer to get started with the basics of Open Source development and Social Coding.

Software Architecture

po4a is architectured around the idea of TransTractors, that are specific parsers in charge of separating the document structure from the translatable content, and to reinject the translated content back into the structure. The project overview document contains a section detailing this architecture and hopefuly explaining how to improve the existing parsers, or add new ones. We try to document the source code and simplify it when possible. Please ask any question that may arise.

Several binaries are built around these TransTractors. The po4a command takes automatically care of the translation workflow, updating the po files and translations when needed. Some deprecated tools implement separately the steps of the translation workflow (but new projects should not use them as they are deprecated): (po4a-translate, po4a-updatepo, and also po4a-gettextize). The implementation of all these tools is sketched in the project overview.

Finding something to hack

  • Check the GitHub issues. Search in particular for the tasks are marked beginner friendly, as they should be accessible even if you're just starting with the po4a development.
  • Check the Debian bug reports, since most of these reports are not related to Debian in any way. Actually, they should be forwarded to the GitHub issue tracker, but it's easier to read them on Debian directly. Some of them are tagged as "new comer" (this list may be currently empty when you click it, though).
  • Check the TODO file in the archive. This file often gets outdated, but you may find some inspiring notes.
  • Add support for a new format. The best is to add support for a format that you need yourself, or to convince some prospective users. There is no better testing to a new TransTractor than the translation of a large document used in production somewhere. Don't forget to add all relevant tests to your format.
  • po4a comes with a fairly large amount of documentation. You are welcome to fix or report any typo or errors. It would be good to improve this documentation to follow the Best Practices from WriteTheDocs, and many sections would need a full rewriting to be in proper english. We should however refrain from superfluous changes when possible to reduce the burden on our translators (hint: rephrasing globish to english is NOT a superfluous change).

Testing your changes

Of course you should make sure that your PR does not break any test to get accepted. If you fix an issue or add a feature, we may be reluctant to integrate your change without a new dedicated test, to ensure that bugs won't resurface in the future.

  perl Build.PL
  ./Build test

Test dependencies:

  • On Debian: check the .travis.yml file in the root directory for a full list.
  • On Fedora 24 (if you installed from the rpm po4a package): perl-SGMLSpm perl-TermReadKey perl-Text-WrapI18N perl-Module-Build perl-Test-Simple perl-Unicode-LineBreak perl-HTML-TokeParser-Simple docbook-dtds
  • On openSUSE Leap 15.2: perl-SGML-Parser-OpenSP perl-TermReadKey perl-Text-WrapI18N perl-Module-Build perl-Test-Simple perl-Unicode-LineBreak perl-HTML-TokeParser-Simple docbook-dtds

When writing or improving a test, you probably want to select the test to run, and make it verbose. The tests are executed from the "t" directory.

  ./Build test --test_files t/fmt-yaml.t verbose=1

The PERL5LIB variable can be used to run your modified modules without reinstalling everything:

  PERL5LIB=../lib/ perl ../po4a-normalize -f text -o markdown t-20-text/PandocYamlFrontMatter.md

To the opposite, if you want to test the installed binaries instead of the local ones, simply set the AUTOPKGTEST_TMP variable:

  AUTOPKGTEST_TMP=1 ./Build test

The test harness changes the permissions of many files and directories to ensure that each test remain limited to their own directory. If you interrupt the tests, they may fail to restore the previous situation. In this case, just run the first "test" that is in charge of restoring any possible mess that the other tests could introduce.

  ./Build test --test_files t/00-perms.t

Writing a test

In order to define a new test, you can use some convenience helpers. If you follow some conventions, you don't have to write much boilerplate code.

Each test is defined using a perl hash with several keys. Every test should have the key doc, which contains a short description of the test.

Currently the test suit supports 3 types of tests:

  • po4a.conf - to test the po4a utility
  • format - to test the specific format modules
  • run - old generic run-commands-tests that wasn't or couldn't be converted to one of the above formats

Also, you can mark a test as TODO with the hash key "todo". Usually, it's best to write a short description or to add a link to the online bug report.

Example:

push @tests,
  {
    'format'    => "wml" 
    'input'     => "fmt/wml/general.wml",
    'todo'      => "https://github.com/mquinson/po4a/issues/138",
  };

po4a.conf tests

Thees tests are used to check how well po4a can handle different options in a po4a.conf see example tests and Testhelper.pm for more details.

Format tests

If you need to test the output of a module, you should define at least two keys in the hash: format and input. The first one specifies the format which will be passed to option -f of utilities like po4a-translate or po4a-normalize. The second one specifies the input file to perform the tests on. It is not strictly necessary to specify the doc key, but it is encouraged if you have more than one test for a single format.

See for example the manpage tests for some simple test definitions.

The "format" tests expect to find the next five files:

  1. The master file (input) used as input for po4a.
  2. The expected normalized file, with the same basename and the ".norm" extension. (May be overridden with norm key).
  3. The expected .pot file, again with the same basename as the master file and the extension ".pot" (May be overridden with potfile key).
  4. The expected .po file, using again the same basename and the extension ".po" (May be overridden with pofile key ).
  5. The expected translated file, again with the same basename and the ".trans" extension. (May be overridden with trans key).

Here's an example. If you define the following hash:

push @tests,
  {
    'format' => 'man',
    'input'  => 'fmt/man/null.man'
  };

... you need to have the following five files:

fmt/man/null.man
fmt/man/null.norm
fmt/man/null.pot
fmt/man/null.po
fmt/man/null.trans

The actual language of PO-files does not generally matter, but all existing format tests use uppercase of the original strings for translations so it would be easier to all contributors.

The master file you have to write yourself, the rest could be easily generated with po4a-normalize:

cd t/fmt/man/
PERL5LIB=../../../lib/ perl ../../../po4a-normalize -f man null.man -l null.norm -p null.pot
PERL5LIB=../../../lib/ perl ../../../po4a-normalize -C -f man null.man -l null.trans -p null.po

... but you should furiously check those, that they are actually what you expect.

The format tests also have other options. For full list and description see comments in Testhelper.pm.

Run tests

If you need to have more control over your tests, you can use the "run" and "test" keys in the hash. The "run" key defines the commands to run; the "test" key has the commands to check the generated output.

Submitting Your Patch

Before all, please run tidyall -git to ensure that your changes stick to the project quality standards. You should also consider using a git pre-commit hook to that extend.

When submitting a patch, please either fill a Pull Request on mquinson/po4a on GitHub or a Merge Request on mquinson/po4a salsa instance of GitLab. If you go for the salsa server, please do not fill your MR against the debian/po4a repository that is dedicated to the packaging of the software (unless, of course, your change is against the packaging). Your request should be based on the latest code in the master branch. Please rebase your work as needed.

Finally, all PRs should include an update the the NEWS file. Please follow the format and briefly describe the change and provide a reference to the PR or issue. Please place your update at the bottom of the list in the appropriate section for the next, as yet unreleased, version. Please add sections as needed for various formats.

Translating

You can translate the runtime messages, the documentation and the website. Please prefer the weblate interface at https://hosted.weblate.org/projects/po4a/ even if we also accept pull requests for that.

On need, you can manually refresh the translation files as follows:

 perl Build.PL
 ./Build postats # Refresh the pot and po files (both doc and bin)

The documentation is written using the PerlDoc format (pod), as described here: http://perldoc.perl.org/perlpod.html

Reminder for the po4a maintainers

This is mostly a note to ourselves. But who knows? Maybe you are (or soon will be) one of us? You're welcome here.

Interacting with weblate

It's easy to get a conflict when changing the po files while the translators are working. To avoid this, you should use the weblate client. Add the following content to ~/.config/weblate:

[keys]
https://hosted.weblate.org/api/ = APIKEY (find it on https://hosted.weblate.org/accounts/profile/#api)

Then, when you have to change the po files, lock weblate, flush weblate, integrate the changes locally, push your changes to the git, pull them on weblate, and unlock it. You need to be a maintainer of the project on weblate for that.

git pull salsa master ; git push # Get the German and Italian translations
wlc lock
wlc commit
wlc push
# Merge the pull request on github
git pull
# Do and commit your local changes
perl Build.PL
./Build
git commit -m "update POT files" po/*/*.pot # don't commit PO files to reduce conflicts; weblate update them
git push
git push salsa
wlc pull
wlc unlock

Here is how to integrate a PR that fixes typos in english without fuzzying the translations (using msguntypot):

wlc lock && wlc commit && wlc push
# Merge the weblate PR on github
git pull
# Merge the other PR on github
git pull
rm -rf po_orig ; cp -r po po_orig # Copy existing po files
# Fix the typo in the doc
./Build postats # Refresh the pot and po files (both doc and bin)
cp po_orig/bin/*.po po/bin # Restore po files; msguntypot will handle typos in msgids
cp po_orig/pod/*.po po/pod
msguntypot -o po_orig/bin/po4a.pot     -n po/bin/po4a.pot     po/bin/*.po
msguntypot -o po_orig/pod/po4a-pod.pot -n po/pod/po4a-pod.pot po/pod/*.po
rm -rf po_orig
git commit -m "unfuzzy translations after the typo fixes in english" po
git push
wlc pull && wlc unlock

Releasing po4a

Here is the checklist of things to remember when releasing po4a:

  • Integrate all pending translations:

    • wlc commit && wlc push
    • merge the pull request
    • git pull && git pull salsa master

  • Bump the version number in lib/Locale/Po4a/TransTractor.pm and regenerate the building script: perl Build.PL

  • Check that ./Build test reports no error.

  • Generate translation statistics: ./Build postats

  • Check NEWS

    • It documents all recent changes found in git logs.
    • It contains a release name and a release date.
    • It contains the translation statistics. Paste here the output from the command above.

  • Build the archive: ./Build dist

    • Interrupt it if the MANIFEST is out of sync, and then fix it by adding the missing files to MANIFEST (or MANIFEST.SKIP if they should not be released to the users)

  • Commit your changes, eg with commit log like "Releasing v0.XXX"

  • Tag the git and push it: git tag v0.XXX && git push --tags

  • Edit the release on GitHub.

    • Reuse the release name and paste the changelog of this release.
    • Also upload the tarball to the github release: the file META.yml is missing from the tarball generated automatically (see #115). A link to the tar.gz in the text is not enough (see #469).

  • Announce the release on the Mailing List.

  • Add a News entry to the website, update VERSION, rebuild it, and re-push it

  • Put a template in NEWS (using figlet v0.XXX)

  • Change the version in lib/Locale/Po4a/TransTractor.pm to 0.XX-alpha