Skip to content

Add a CONTRIBUTING.md file #24489

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Leont merged 1 commit into from
Jul 28, 2026
Merged

Add a CONTRIBUTING.md file #24489

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Contributing to perl

There are several documents trying to help you on your way to contribute to our project,
including `pod/perlhack.pod`, `pod/perlhacktips.pod` and `pod/perlhacktut.pod`.

Please be mindful of `CODE_OF_CONDUCT.md` and `AI_POLICY.md`.

Comment thread
Leont marked this conversation as resolved.
## In brief:

* Before opening any non-trivial pull request, open an issue first. New syntax and features should definitely be discussed in advance, with many of these likely to have to go through the [PPC process](https://github.com/Perl/PPCs/) before any PR will be accepted. Starting to code before there's agreement on how to approach something often leads to wasted effort.

* Be sure run `make test` before opening a PR, or `make -j$(nproc) test_harness TEST_JOBS=$(nproc)` if you're in a hurry.

@richardleach richardleach Jun 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add something like: "If the PR touches anything to do with memory allocation or management, including altering the lifecycle of allocations, changing bounds checks, modifying struct definitions, and so on, please ensure that all tests run successfully under asan or valgrind."

@bulk88 bulk88 Jun 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Egh, those are Linux only products AFAIK. A make test on a -DDEBUGGING build is pretty tough on getting it to pass for anything but the simplest of tweaks. It's been a very long time since I've used this feature on Windows, but there is a feature called GFlags which is a blacklist in the registry of exe file names or exe absolute paths which if they start a process, the MS system DLLs and NT Kernel are rewired to be in a slower hyper paranoid asserting verifying everything mode
https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/gflags-flag-table

I usually hit the check marks for FLG_ENABLE_HANDLE_EXCEPTIONS
FLG_HEAP_ENABLE_FREE_CHECK
FLG_HEAP_VALIDATE_PARAMETERS
FLG_HEAP_ENABLE_TAIL_CHECK

Poison patterning the entire block on free(), and tail check which adds something like 4, 8, maybe 16 bytes more secret space to the end of the malloc block and keeps a poison pattern in there that is checked on the next realloc() or free() are 2 most important features IMO. Tailcheck would detect an overwrite as small as 1 byte above the whatever the formal byte count was for that block. The Win32 heap has always featured the BSD only msize() feature, which it calls HeapSize(), which could be used as a strlen() replacement in production code but I've never seen any POSIX FOSS or Win32 in life use msize() or HeapSize as an alternative to tracking length explicitly in end developer created fields. Internally/undoced WinOS keeps the number of missing/unrequested user visible bytes below the next allocation granularity boundary in the byte right before the next granularity boundary. 1 bit in the malloc block header says if the block byte size is an aligned unit of 8 or 16 or 24 or 4096ish or has upto 7/15/23 bytes smaller.

make test_porting is the highest importance pre Pull Request task to remember to do in my opinion. It's fast enough, and guarantees a couple perl process launches ran without a SEGV. The P5P GH smoke farm already follows this opinion, but IMO it's alot of visual noise for a PR to be submitted that fails the P5P GH smoke.

Perhaps instead of a generic discouraging "we don't allow anything but 1 line bug fixes without a ballot committe quorum being raised, a motion to schedule a submission, and a vote on docketing the proposal to the proposal committee", there could be a list of prior PRs or mailing list threads of examples which should have been PPC back then had PPC existed back then, or a couple hand picked good (best) examples of PPC changes.

Full time Perl devs or full time Perl and C devs know what PPC is, but a random C dev or random sysadmin will have no idea what the burocracy policy and regulation talk is, and won't bother going through the process to upstream to P5P whatever they did locally with their Perl if the Perl 5 Contribution Policy sounds like 🍎 🍏's or Google's definition of open source software, i.e. we don't allow non-staff intellectual property in our code bases, we only make the source code available for amateur or professional Infosec people to review it for backdoors and exploits, or our software links to 3rd party FOSS libs and those FOSS libs have infective licenses and it's not worth it for us to clean room reimplement them.

@tonycoz tonycoz Jun 24, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Egh, those are Linux only products AFAIK

I haven't tried it, but:

https://learn.microsoft.com/en-us/cpp/sanitizers/asan?view=msvc-170

* If this is your first contribution, please don't forget to run `perl Porting/updateAUTHORS.pl` after committing (and committing the result), otherwise the `AUTHOR` file tests will start failing.
1 change: 1 addition & 0 deletions MANIFEST
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ configpm Produces lib/Config.pm
Configure Portability tool
configure.com Configure-equivalent for VMS
configure.gnu Crude emulation of GNU configure
CONTRIBUTING.md Guidelines on how to contribute to the project
cop.h Control operator header
Copying The GNU General Public License
cv.h Code value header
Expand Down