Contributing to the Evergreen Community

This guide provides essential information for Bibliomation team members contributing code and documentation to the Evergreen open-source community.

Overview

As part of Bibliomation’s commitment to the Evergreen community, team members regularly contribute bug fixes, enhancements, and documentation improvements. This collaborative approach strengthens the entire Evergreen ecosystem while ensuring our local improvements benefit all users.

Before contributing:

Documentation Contributions (GitHub - Recommended)

The Evergreen community prefers documentation contributions through GitHub pull requests for easier review and collaboration.

Setup and Workflow

  1. Fork and clone:

    # Fork https://github.com/evergreen-library-system/Evergreen on GitHub
git clone https://github.com/yourusername/Evergreen.git
cd Evergreen
git checkout -b docs-your-feature-name

  2. Make changes and submit:

    # Edit files in docs/modules/ using AsciiDoc format
git add .
git commit -m "Docs: Descriptive commit message"
git push origin docs-your-feature-name
# Create pull request on GitHub

  3. For simple typos: Use GitHub’s web interface to edit files directly and create pull requests

Code Contributions (Traditional Git Workflow)

Code contributions follow the established Evergreen git workflow with Launchpad integration.

Initial Setup

  1. Generate SSH key (if needed):

    ssh-keygen  # Accept defaults, optionally set passphrase

  2. Request access: Email your public SSH key (~/.ssh/id_rsa.pub) to gitadmin@evergreen-ils.org

    Send only your public key (.pub file), never your private key!

  3. Configure Git:

    git config user.email "your.email@biblio.org"
git config user.name "Your Name"
git config commit.template commit-template

  4. Clone and setup remotes:

    git clone git://git.evergreen-ils.org/Evergreen.git
cd Evergreen
git remote add working git://git.evergreen-ils.org/working/Evergreen.git
git remote set-url --push working git@git.evergreen-ils.org:working/Evergreen.git
git fetch --all

Code Workflow

  1. Create branch using Launchpad bug number:

    git checkout -b lp1901615-fix-circulation-renewal origin/main

    Branch names must follow: lp#-brief-description

  2. Develop and commit with sign-offs:

    git commit -as  # Sign-off required for all contributions

  3. Push to working repository:

    git push working lp1901615-fix-circulation-renewal:user/yourusername/lp1901615-fix-circulation-renewal

  4. Link to Launchpad: Add pullrequest tag with branch link to the bug

Feature Development

For significant changes:

  1. Propose on the development mailing list first

  2. Create design document in the dev:proposal namespace

  3. Wait for feedback before implementing

  4. Follow standard workflow once approved

Commit Standards and Quality

Commit Messages

Include:

  • Clear subject (< 80 characters)

  • Launchpad number (LP#12345) when applicable

  • Signed-off line (git commit -s)

  • Release note for user-facing changes:

    LP#12345: Fix circulation issue with renewals

This resolves an issue where auto-renewals would fail
for items with specific loan periods.

Release-Note: Fixes auto-renewal failures for certain loan periods
Signed-off-by: Your Name <your.email@biblio.org>

Quality Requirements

  • pgTAP tests for database changes

  • Perl tests for bug fixes when feasible

  • Angular linting for staff client: cd Open-ILS/src/eg2 && npx ng lint

  • Documentation updates for new features

Branch Management and Collaboration

# User branches (only you can push)
git push working feature:user/yourusername/lp1234567-feature-name

# Collaborative branches (others can contribute)
git push working feature:collab/yourusername/lp1234567-feature-name

# Test others' work
git checkout -b local-test working/user/otherperson/lp9876543-their-feature

# Add sign-offs when testing
git cherry-pick -s commit-hash

Using Launchpad

Bug Reports

Search existing bugs first, then create detailed reports with: * Evergreen version * Reproduction steps * Expected vs. actual behavior * System information (PostgreSQL, browser, etc.)

Linking Contributions

  • Add pullrequest tag to bugs with code changes

  • Include working repository branch link

  • Respond promptly to community feedback

Troubleshooting

Access Problems

If you can’t push to working repositories:

  1. Verify SSH key was sent to gitadmin@evergreen-ils.org

  2. Confirm SSH URL usage (not git://) for pushing

  3. Contact git administrators for username verification

Resources and Support

Documentation

Community Support

Best Practices

  • Follow community coding standards and existing patterns

  • Write clear commit messages explaining problems and solutions

  • Test thoroughly on development systems before submitting

  • Be responsive to community feedback

  • Test on multiple environments when possible

  • Include comprehensive documentation for new features

Recognition and Career Benefits

Contributing to Evergreen provides valuable open source credits that can enhance your professional profile:

  • GitHub contributor graph: Your contributions appear on the GitHub contributors graph, showing commit frequency and totals over time

  • Community recognition: Your name is listed in the official Evergreen contributors list

  • Release notes: Contributions are credited in release notes for versions that include your commits

  • Professional portfolio: Open source contributions demonstrate real-world development skills to potential employers

  • Industry networking: Participation connects you with library technology professionals worldwide

These contributions create a permanent, public record of your technical skills and community involvement - valuable assets for career advancement in library technology and software development.

Remember: Contributing to open source is a learning process. Don’t hesitate to ask questions and engage with the community!

See also