Thank you for taking an interest in flextable. This document explains how the project is run, what kinds of contributions are useful, and what to expect after you open something.
Please read it before opening an issue or a discussion. It exists so that your time and mine are both spent well.
How this project is maintained
flextable is maintained by one person, unpaid, alongside client work. There is no team behind it and no service-level agreement.
Practically, this means:
- Response times vary from days to months. Silence is not a rejection, and it is not an approval either.
- The number of open issues I can hold in my head at once is small. Opening several requests in parallel does not make them move faster; it makes all of them move slower.
- Changes that have been discussed and agreed on are the ones that get done.
Where to put what
| You want to… | Go to |
|---|---|
| Ask how to do something with flextable | The documentation and the book, then Discussions |
| Report a reproducible bug | Bug report |
| Suggest a feature or an API change | An issue, one per request |
Answers to usage questions come from the community, when someone has the time.
Usage questions belong in Discussions, not in the issue tracker; I may move them there or close them with a pointer here. That is housekeeping, not hostility.
Bug reports
A bug report needs a reprex and the output of sessionInfo(), run after loading the packages of the example. Both are required.
A reprex is minimal, self-contained, and runs in a fresh R session. Use tempfile() rather than local paths, and a small dataset (a built-in one such as iris or mtcars, or a few rows created in the code). Reduce the table to the smallest one that still shows the problem.
Say which output is wrong: Word, PowerPoint, HTML, PDF, Typst, RTF or an image (plot(), gen_grob(), save_as_image()), and how it is produced (save_as_docx(), officer, R Markdown, Quarto…). For a document made with R Markdown or Quarto, give a minimal document that shows the problem. A screenshot of the result helps, but does not replace the code.
Reports without an executable reprex will usually be closed, however carefully they are written. This is not a judgement on the report; it is that diagnosing a rendering problem without the code that produces it is not possible.
Feature requests and API changes
Feature requests are opened as issues. Some of them take me a long time to come back to: an open issue without an answer is not forgotten.
Please describe the problem you ran into, not the API you would like to see. A concrete blocked task tells me what needs to be true; a proposed function signature only tells me one of the many ways to get there, and usually the one that is cheapest to imagine rather than cheapest to maintain.
A good request contains:
- the task you were trying to accomplish
- the code you wrote and where it stopped working
- what you did instead, if there was a workaround
- why the workaround is not good enough
One request per issue. A single thread proposing six changes cannot be answered: some parts will be reasonable and some will not, and there is no way to say yes or no to it as a whole.
What is unlikely to be accepted
- Changes to existing defaults or signatures. flextable is used by many packages and in the reporting pipelines of an unknown number of people, clinical and regulatory reports included. A change that looks like a small consistency fix here can break code I will never see. Deprecation cycles are long and expensive, so the bar for starting one is high.
- Broad new API surface. Every exported function is a permanent commitment: documented, tested, supported in every output format, and impossible to remove cheaply. Requests that amount to a new subsystem will generally be declined, not because they are bad ideas but because I cannot maintain them.
- Features for one output format only. flextable produces the same table in Word, PowerPoint, HTML, PDF, Typst, RTF and images. A feature that only one format can render is hard to justify, unless the format itself requires it.
- Features aimed at a tool rather than a user. “Package X or agent Y would find this convenient” is not by itself a reason to change flextable. The question is whether people are blocked on a real task.
Being declined is not a verdict on the idea. Very often the right home for it is your own package built on top of flextable.
Pull requests
Pull requests are not accepted. Changes are made by the maintainer.
This is not a judgement on anyone’s work. A pull request is a request to review, merge, and maintain code forever, and I cannot take that on.
If you want a change, describe the problem in an issue, as explained above, before writing any code. Code you have already written can live in your own fork or package.
Code and AI
Please do not send code, whether written with an assistant or not. Thanks to AI, or because of it, redoing a change from the idea is now much easier for me than reviewing code written by someone else. What is valuable is the real problem you ran into.
For the same reason, please do not open generated audits or lists of what the package is missing. They take minutes to produce and hours to answer. A bug report needs a reprex that you ran yourself.
Working on the code
This is useful if you work on your own fork, or want to look at a bug yourself:
install.packages(c("devtools", "testthat", "roxygen2"))
devtools::load_all()
devtools::test()Conventions:
-
Documentation is written with roxygen2, in markdown, in English. Run
devtools::document()to generate the.Rdfiles. - Tests use testthat (3rd edition). Most of them check the content written for each output format (XML for Word and PowerPoint, HTML, LaTeX, Typst, RTF) and the sizes computed for the tables.
Being civil
Be civil. Assume the other person is busy rather than rude, in both directions. Repeated pressure on unanswered threads, or hostility toward contributors or maintainers, will get you blocked from the repository.
A closing note
Most of the rules above exist because of things that went wrong, including things I got wrong, like leaving well-intentioned proposals unanswered for far too long. The point of writing them down is that the process should not have to be renegotiated from scratch every time, and that nobody should have to guess where they stand.
