mirror of
https://github.com/libexpat/libexpat.git
synced 2026-01-27 01:44:29 +00:00
103 lines
3.3 KiB
Markdown
103 lines
3.3 KiB
Markdown
# Hi! :wave:
|
|
|
|
Thanks for your interest in contributing to the libexpat project or "Expat"! :+1:
|
|
|
|
> [!TIP]
|
|
> TL;DR: **The best move before creating a pull request**
|
|
> that is big, complex, and/or controversial
|
|
> is to [open a new issue](https://github.com/libexpat/libexpat/issues)
|
|
> and discuss options moving forward :pray: :beers:
|
|
|
|
Below, I'll document what Expat needs and does not need, at this time.
|
|
|
|
|
|
# What Expat needs (and does not need) in general
|
|
|
|
Expat is:
|
|
|
|
- in maintenance mode,
|
|
- unfunded,
|
|
- understaffed,
|
|
- complex,
|
|
- 25+ years old in some regards,
|
|
- meant to support parsing of XML files that exceed available RAM,
|
|
- written in the memory-unsafe language C99,
|
|
- is [used in many places](https://libexpat.github.io/doc/users/),
|
|
both in [hardware](https://libexpat.github.io/doc/users/#hardware)
|
|
and in [software](https://libexpat.github.io/doc/users/),
|
|
- implementing [XML 1.0 *Fourth* Edition](https://www.w3.org/TR/2006/REC-xml-20060816/),
|
|
- targeting environments that are relevant today
|
|
and/or up to 5 years into the past.
|
|
|
|
|
|
## What kinds of pull requests will be welcome
|
|
|
|
Pull requests will be most welcome when they:
|
|
|
|
- are small,
|
|
- are easy to review,
|
|
- have low risk,
|
|
- have had GitHub Actions CI run and all-green already
|
|
in your public fork repository,
|
|
- help both you and the libexpat project :tada:
|
|
|
|
The need for additional tests or CI will depend on the specific pull request.
|
|
|
|
|
|
## What kinds of pull requests will *not* be welcome
|
|
|
|
Pull requests will *not* be welcome when:
|
|
|
|
- the changes are big, complex, high risk, controversial
|
|
and/or hard to review,
|
|
- the exact change has been said "no" to in the past,
|
|
- the changes break API or ABI backwards compatibility,
|
|
- it fixes an issue for an unsupported
|
|
(or no-longer supported) environment, and/or
|
|
- it introduces new features
|
|
(without prior discussion and agreement
|
|
in a dedicated issue).
|
|
|
|
Specific examples of things known to *not* be welcome:
|
|
|
|
- Mass-changing things.
|
|
- Fixing things for some stone age version of Visual Studio.
|
|
- Adding support to ignore or recover from malformed XML.
|
|
- Adding support for XML streaming.
|
|
- Making the C code compile with a C++ compiler.
|
|
- Adding support for XML 1.0r5 without prior discussion.
|
|
- Adding support for XML 1.1 in general.
|
|
- Adding additional build systems.
|
|
|
|
|
|
# What Expat needs on a technical level
|
|
|
|
- All new C code and changes to existing C code must:
|
|
- pass all existing CI
|
|
(that includes
|
|
[ASan](https://clang.llvm.org/docs/AddressSanitizer.html),
|
|
[UBSan](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html),
|
|
[clang-format](https://clang.llvm.org/docs/ClangFormat.html),
|
|
[Cppcheck](https://cppcheck.sourceforge.io/),
|
|
[codespell](https://github.com/codespell-project/codespell),
|
|
..),
|
|
- conform to C99,
|
|
- check returns from `malloc`/`realloc` for `NULL`,
|
|
- not use recursion (when it can be controlled by user input),
|
|
- have integer overflow in mind,
|
|
- have undefined behavior in mind, and
|
|
- have security in mind in general.
|
|
- A commit should be about one — and just one — of these things:
|
|
- fixing a bug,
|
|
- improving something,
|
|
- adding something new,
|
|
- doing a refactoring, or
|
|
- adjusting whitespace.
|
|
|
|
|
|
# Providing feedback
|
|
|
|
Thanks for your interest and attention! :+1:
|
|
|
|
I'm happy about [constructive feedback](mailto:sebastian@pipping.org) to this document — thank you! :pray:
|