Contributing to PVXS¶

Thank you for your interest in contributing to PVXS! This guide will help you get started.

How to Contribute¶

The recommended path for including changes is through Pull Requests.

Development Workflow¶

Fork the repository on GitHub
Clone your fork and create a feature branch
Make your changes following the coding guidelines below
Add tests if applicable
Run the test suite: make runtests
Submit a pull request with a clear description of your changes

Reporting Bugs¶

Before reporting a bug, please check if the issue has already been reported.

When reporting a bug, please include:

EPICS Base version or VCS commit
PVXS module version or VCS commit
libevent version (run pvxget -V to show these)
EPICS host and target architectures (e.g., “linux-x86_64”)
Host OS name and version
Compiler name and version
The values of any $EPICS_PVA* environment variables which are set
Any local/site modifications to PVXS or libevent
Concise instructions for reproducing the issue

Additional information which may be relevant:

Number of network interfaces if more than one
Whether clients and/or servers are on the same host or different hosts
Whether clients and/or servers are in the same subnet or different subnets
Whether network traffic crosses between virtual machines and physical hosts
Firewall rules on UDP traffic to/from port 5075 or TCP connections to port 5075
Any local/site modifications to EPICS Base

If the module has built successfully, running pvxinfo -D will report much of this information.

See :ref:reportbug <api/details:reportbug> for more details.

Coding Guidelines¶

C++ Code Style¶

When changing C++ code, please:

Indent with 4 spaces. No hard tabs. UNIX style line endings.
Try to maintain the style of surrounding code.
Include meaningful code comments where reasonable.
Add doxygen tags @since UNRELEASED when documenting additions/changes to public APIs.

Do not:

Add any C++ global constructors or destructors in the pvxs library. (OK in tools, examples, or tests)

Commit Guidelines¶

When committing changes, please:

Include a commit message explaining what and why
Break up changes into multiple commits where reasonable
Include whitespace-only changes as separate commits

Good commit messages:

Start with a short summary (50 characters or less)
Include a detailed explanation if needed
Reference issue numbers if applicable

Example:

Fix memory leak in Value array handling

When cloning Value arrays with shared_array, the reference counting
was not properly updated. This fixes the leak by ensuring proper
shared_ptr handling.

Fixes #123

Testing¶

Running Tests¶

Always run the test suite before submitting a pull request:

make runtests

The test suite will verify:

Unit tests for core functionality
Integration tests with network operations
Compatibility with different configurations

Writing Tests¶

When adding new features, please include tests:

Unit tests for new functions/methods
Integration tests for new functionality
Regression tests for bug fixes

Test files are located in the test/ directory.

Development Setup¶

Prerequisites¶

EPICS Base >= 3.15.1
libevent >= 2.0.1 (or build bundled version)
C++11 compliant compiler
Git

Building for Development¶

# Clone your fork
git clone https://github.com/YOUR_USERNAME/pvxs.git
cd pvxs

# Add upstream remote
git remote add upstream https://github.com/epics-base/pvxs.git

# Configure and build
cat <<EOF > configure/RELEASE.local
EPICS_BASE=/path/to/epics-base
EOF

make

Building with Debug Symbols¶

# Enable debug build
export EPICS_HOST_ARCH=linux-x86_64-debug
make clean
make

Pull Request Process¶

Update your fork with the latest changes from upstream:

git fetch upstream
git checkout main
git merge upstream/main

Create a feature branch:

git checkout -b feature/your-feature-name

Make your changes and commit them:

git add .
git commit -m "Description of changes"

Push to your fork:

git push origin feature/your-feature-name

Create a Pull Request on GitHub
Respond to feedback and make requested changes

Pull Request Checklist¶

Before submitting, ensure:

[ ] Code follows the coding guidelines
[ ] Tests pass (make runtests)
[ ] Tests added for new functionality
[ ] Documentation updated if needed
[ ] Commit messages are clear
[ ] No global constructors/destructors in library code
[ ] Doxygen tags added for public API changes

Documentation¶

When adding or modifying features:

Update relevant documentation in the documentation/ directory
Add examples if appropriate
Update this guide if the contribution process changes
Add release notes for user-visible changes

Code Review¶

All contributions will be reviewed before merging. Please:

Be responsive to review comments
Address all feedback
Keep discussions focused and constructive
Be patient - reviews may take some time

Expert APIs¶

Some APIs are marked as “Expert” APIs and may change incompatibly in minor releases. If you need to use or modify Expert APIs:

Contact the maintainers first
Understand that changes may be more disruptive
Consider proposing promotion to regular API if widely useful

See :ref:expertapi <api/details:expertapi> for details.

Release Policy¶

PVXS follows Semantic Versioning:

MAJOR: Backwards incompatible API changes
MINOR: New features with backwards compatibility, or ABI incompatible changes
PATCH: Bug fixes with backwards compatibility

See :ref:relpolicy <api/details:relpolicy> for details.

Getting Help¶

If you have questions about contributing:

Check existing GitHub Issues
Search EPICS Tech-Talk archives
Ask questions in a new GitHub issue (tagged as “question”)
Review the :doc:api/overview documentation

Contributors¶

Thanks to all who have contributed to PVXS! See the contributors list.

This project is supported by:

Additional Resources¶

:ref:contrib <api/details:contrib> - Detailed information from RST documentation
:ref:reportbug <api/details:reportbug> - How to report bugs
:ref:relpolicy <api/details:relpolicy> - Version numbering and release process
:ref:expertapi <api/details:expertapi> - Information about Expert APIs

Acknowledgments¶

This contributing guide was created and organized by K. Gofron, Oak Ridge National Laboratory, December 28, 2025.