Contributing to fduthesis

Thank you for your interest in improving fduthesis! This template relies on the open-source community, Fudan alumni, and active students to stay up-to-date with both university guidelines and LaTeX3 advancements.

We welcome bug reports, feature requests, and pull requests via our GitHub repository.

Understanding the Codebase

fduthesis is developed using Literate Programming concepts standard in modern LaTeX package development.

  • The core logic is NOT written directly into .cls or .sty files.
  • Instead, the source code and documentation are intertwined inside .dtx (Documented TeX) files located in the source/ directory.
  • We use the l3build system (the official build system of the LaTeX3 project) to unpack these .dtx files into usable classes, compile the documentation, and run automated tests.

Setting Up the Development Environment

To contribute code, you must have a complete TeX distribution (TeX Live or MacTeX) and a basic understanding of terminal commands.

  1. Fork the repository on GitHub.

  2. Clone your fork locally: 

    git clone https://github.com/YOUR_USERNAME/fduthesis.git
cd fduthesis

  3. Create a new branch for your feature or bugfix: 

    git checkout -b feature/my-new-feature

Compiling the Source

Whenever you make changes to the .dtx files in the source/ folder, you must rebuild the package to see the effects.

To unpack the .dtx files and generate the usable .cls, .def, and .sty files: 

l3build unpack

To build the PDF documentation manuals (fduthesis.pdf, fduthesis-en.pdf, and the highly technical fduthesis-code.pdf): 

l3build doc

Running the Test Suite

LaTeX development is highly prone to regressions. A small change in layout logic might break page numbering or bibliography generation. To prevent this, we use l3build for strict regression testing.

To run the entire test suite locally: 

l3build check

How Testing Works

Tests are located in the testfiles/ directory. Each test consists of a .lvt (LaTeX verify test) file containing a minimal document, and a .tlg (Test log goal) file containing the exact expected console output.

When l3build check runs, it compiles the .lvt files and compares the newly generated logs against the .tlg files. If they match, the test passes.

If you are adding a new feature, you are highly encouraged to add a corresponding .lvt file to verify its behavior.

Submitting a Pull Request

  1. Ensure your code follows the LaTeX3 naming conventions and coding style (expl3).
  2. Run l3build check locally and ensure all tests pass.
  3. Push your branch to GitHub and open a Pull Request (PR).
  4. Our GitHub Actions CI pipeline will automatically test your PR against Ubuntu, macOS, and Windows environments, utilizing multiple TeX engines (xelatex, lualatex).
  5. A maintainer will review your code, request changes if necessary, and merge it into the main branch.