GitHub Guidelines and Process

Last Updated: 2025-03-14

Future revisions must be communicated with the team to provide an opportunity to review.

Important Definitions

  • Testers: Often referred to as quality assurance (QA) engineers, are responsible for verifying that the software works as intended and meets the specified requirements. They focus on identifying defects and ensuring the overall quality of the software product.

  • Developers: Also known as programmers or software engineers, are responsible for creating software applications. They write the code, design the software architecture, and implement features based on requirements.

  • Usability Group: A focused group of Specify staff is consulting and providing feedback on the user experience and usability of newly developed and in-development capabilities, meeting semi-regularly to discuss user challenges.

  • PR: A pull request (PR) is a proposal to merge changes from one branch of a project into another. It’s a way for developers to collaborate and get feedback on their code before merging it into the main project.

  • Regression: Refers to when a software feature stops working after changes are made to the code or environment. This can include new features, bug fixes, system upgrades, or configuration changes.

  • Agile Development: Agile development is a project management approach that involves breaking work into smaller tasks and delivering them incrementally. It’s an iterative and flexible way to work that emphasizes collaboration and responding to change.

  • Issue: Refers to a problem, bug, or defect in the software that needs to be addressed. This can include anything from software malfunctions to usability problems.

  • Feature Request: A suggestion for new functionality or enhancements to existing features in the software. It reflects users’ needs or desires for additional capabilities.

  • Requirements: The specifications and conditions that a feature/change must fulfill to meet the needs of its users and stakeholders. They serve as a foundation for the development process, guiding the design, implementation, and testing of the software.

Expectations (All Staff)

Communication

  • Make sure to acknowledge messages relevant to your work in public channels by reacting to them.

    • Think of it as being in a physical office—if someone spoke to you directly, you wouldn’t ignore them. A quick reaction shows you’re engaged and aware.

  • Development tasks that impact testing work will be communicated to other channels.

    • Staff should be notified if development decisions impact their work.

  • It is the responsibility of you to review messages for your team’s channel on Slack.

    • e.g. If you are a part of the UX testing team, please review and “react” to messages in the #testing channel. If you are a member of the development team, please do the same in the #sp7-engineering and #development-meeting channels.

  • Updates for milestones must be communicated on a channel where everyone has access.

  • Be thoughtful and respectful to all participants, both within our team and externally.

    • Remember that GitHub is a public space where anyone from our community or beyond can view our discussions.

  • Sensitive information provided by our users or credentials for accessing privileged materials should never be published or shared on GitHub.

Discussing a PR or Issue

  • Slack can be used to discuss points about an issue, but a summary should always be shared publicly on GitHub.

  • A solution to a reported issue should always be shared on GitHub.

    • Private messages and Slack conversations about issues lead to information loss, confusion for other testers, and often requires developers and staff to repeat information several times.

    • Explanations for why an issue is not valid or why there is a problem in how they tested should be communicated publicly.

  • Before closing an issue, please leave an explanation on why it has been closed (e.g. This is not valid because…, Closed in favor of #0000, Duplicate of #1938) and an explanation on why.

  • If you dismiss a testing review, please provide a written explanation for the dismissal.

GitHub Milestones

  • Every upcoming production version of Specify will have all associated issues and PRs captured in the appropriate GitHub Milestone.

  • Each milestone will have items added to it based on the current priorities and development timeline, and this must be discussed regularly by the development team and the usability group.

    • The Usability / Development meeting will inform issues, bugs, features for upcoming milestones, as well as provide feedback on UI for new features.

    • This process takes place 2+ milestones in advance– milestones currently in development should not be substantially adjusted.

  • If items are added to a milestone, often it requires that another item is removed.

  • Milestones should contain fewer than 15 atomized (small as possible) issues for each release. The only exceptions to this are for critical bug fixes or issues discovered during testing, unless otherwise agreed upon as a group.

  • If you discover an issue during internal testing for a milestone release, issues should be immediately assigned the milestone corresponding to that release.

    • After the issue is created, please send a direct message to the development lead.

  • All staff are expected to review future milestones so they can provide feedback on requirements before it is in development and in production.

Test Panel Guidelines

Database Naming Guidelines for the Test Panel

Please ensure compliance with these guidelines to maintain organization and clarity in the test panel.

Database Type

Naming Format

Usage

Example

Master Databases

Must end with YYYY_MM_DD

Only for copies; never used for testing.

ku_fish_2025_03_14

Copy Databases

databaseName_copy_YYYY_MM_DD

Can be used for any Pull Requests (PRs) without migrations.

ku_fish_copy_2025_03_14

Migration Databases

databaseName_issue-XXXX_YYYY_MM_DD

Must include the migration PR name in the title.

ku_fish_issue-2341_2025_03_14

Developer Guidelines

Agile Development Expectations

  • We are a small team, so we need to follow the best practices for agile development.

  • As much as possible, we must break down features into small, manageable goals and tasks.

    • Break into sub-features: Split the feature into logical components (e.g., frontend, backend, API).

    • Isolate dependencies: Identify elements that are dependent on others for easier sequencing.

    • Keep them small: Limit scope to one actionable piece of functionality

    • Identify technical tasks: List what is needed to implement the story (e.g., “Create a database schema”, “Design the UI”) and use that as tasks.

  • Prioritize tasks in sprints (1-2 weeks) with clear goals and deliverables.

  • Ensure all code passes checks (linting, testing, etc.) before merging.

  • Merge production regularly to reduce the risk of git conflicts.

  • Validate every feature against requirements before marking it complete, meeting with the requirement author as needed.

  • Focus on completing tasks thoroughly instead of multitasking.

  • Consult with the usability group regularly to ensure that new features meet existing requirements and prioritize user usability.

Developer Guidelines for PRs

  • Ensure every PR includes developer notes. This is to help with code reviews and documentation when referring to a PR in future.

    • This can be a summary of the implementation (level of detail would depend on the scope of the PR) and document reasonings behind any significant decisions.

    • For bug fixes, this would be notes on what caused the bug initially and how the PR fixes it.

  • A new PR must be created for all utils functions that are created

    • Would be a case to case. We would proceed with this if it’s a broad use across a lot of components.

    • Examples:

      • Const capitalize => ()

      • Const camelToHuman => ()

      • Const sortFunction => ()

      • Const getAttachmentRelationship => ()

      • Const getDateParser => ()

      • Function findClosestZIndex() {}

      • Function useIndent() {}

  • Every migration must be isolated in its own PR

    • Every migration must have a revert and this must be tested by the developer before asking for review.

  • Do not expand the scope beyond the requirements as written, unless said requirements have been revised.

    • If the original requirements or the developer implementation are determined to be unsatisfactory by the usability reviewers, desired changes must be documented in the original issue (requirements) and integrated into the PR.

    • At the end of the review process, you should leave a comment that says “Everything is working, it is acceptable as an MVP. Here is an issue (or list of issues) that describe enhancement possibilities” based on feedback and merge the PR.

  • Rules:

    • Any new requirements commented on the PR should not be included, instead added as new issues

    • Only requirements described in the main feature request should be included in the PR.

      • Do not allow scope creep to drag PRs on beyond the time box accepted.

    • Instructions targeting a specific database/issue are not acceptable alone.

      • Generic instructions are required, specific databases can be mentioned for reference but testing steps must be useful on many dbs.

    • If a tester is requesting a change, do not hesitate to place the request in the dev channel for further review.

  • Merging Rules:

    • Before merging: 2 developer approvals, 2 UX approvals

      • When changes are made to a PR, the developer must re-request review from testers who have previously approved.

      • Only 3 approvals are necessary in cases where the change is minor, not visible to the user, or only possible to test by developers.

    • A PR with the expected approvals should be merged immediately if in the milestone under current development.

      • All known bugs/desired improvements must be captured as new issues immediately following or before the PR being merged with a note on the PR that links to the new issues.

  • Student Hours:

    • Developers can see when testers are available on Google Calendar (job appears after their name)

Tester Guidelines for PRs

When testing instructions are provided, please follow them exactly as written. If there are gaps in the instructions or if it is clear that other areas should be tested, use your judgment to test those cases as needed. If you find any issues related to the instructions, please request changes. For issues not covered by the written instructions, review the PR Scope heading below to determine how to proceed.

PR Scope

If you find an issue while testing a PR and are unsure if it is due to the changes you are testing, please test this behavior in the latest version of production as well.

In Scope

What issues are in scope and acceptable to request changes for:

  • Core functionality: Any code directly implementing the feature, bug fix, or enhancement described in the PR.

  • Refactoring directly tied to the changes: Minor refactoring needed to support the feature.

  • New bug/issue: A bug related directly to the PR that was discovered during testing that cannot be recreated in the branch the PR is based on.

  • Failing requirements: The PR does not address all mentioned requirements in the issue it aims to resolve.

Out of Scope

What is not in scope:

  • Unrelated bugs: Issues that are not directly caused by the feature or fix in the PR.

  • Broad refactoring: Large-scale cleanup or structural changes

  • Performance optimizations: Enhancements not required for the current functionality but identified as potential improvement

  • Additional feature requests: Ideas or changes identified during the PR testing

  • Extensive styling updates: Major UI/UX overhauls or changes unrelated to the core feature

  • Non-blocking edge cases: Handling of less critical scenarios

Approval:

If you go through testing instructions and everything passes, you should then approve the PR.

  • If you have additional questions, you do not need to wait to have an answer before you submit an approval

  • If the comments/suggestions are valid, the developer can and should improve the PR.

  • If it is a regression from v7 behavior, changes can be requested.

  • If it is a bug in the new behavior or tool, a new issue must be made. (see in or out of scope)

Testing Instructions

When copying testing instructions, only retain the checklist items and not the descriptions nor the steps.

  • Comments should be organised into categories

  • Each category should start with the category title then numbered descriptive subtitles

  • Each category should be separated from the others using — to have a visual separation

  • Categories: (See PR Scope section)

    • Improvements
      Suggested enhancements or optimizations that go beyond the current requirements.

    • Requirements
      Failure directly linked to the requirements written in the issue

    • Bugs
      Issues that do not align with the expected behavior outlined in the requirements or critical blockers that, while not directly related to the requirements, hinder the functionality of the feature.

Before

After

Images

To maximize the space used in an issue body, please take care to resize images when appropriate to make it easier to comprehend the content of a request.

Resize Image

You can adjust the size of an image by modifying the width attribute below:

<img src="https://github.com/user-attachments/assets/492a54f0-b26f-4e69-898a-28c0f65e0355" width="500" />

Side-by-side

You can add additional img elements in line below if necessary.

<div style="display: flex; justify-content: space-between; align-items: center;"> 
<img src="https://github.com/user-attachments/assets/492a54f0-b26f-4e69-898a-28c0f65e0355" width="300" /> 
<img src="https://github.com/user-attachments/assets/another-image-link" width="300" /> 
</div>

Testing Checklist

Internal testing for a release requires four passing checks for the checklist to be considered complete.

If the testing lead has assigned you specific rows, prioritize those items first.

Begin testing the lines with the fewest approvals before addressing others. If you mark a row as failed or unsure, always include a comment, and make sure that information is added to GitHub as well as an issue or comment.

Difference Between a Bug & Enhancement

You can read more about the differences between the two concepts here!

Any new feature requests should be added as a new feature request discussion.
Any bug or issue discovered should be a new bug report.

Requirements should currently be written only by the requirement lead. Testers should initiate new discussions as described above, which can later be formalized into requirements.

Bug Report Guidelines

Follow The Template

Make sure to follow all steps asked of you in the bug report template.

If you suspect you have discovered an issue in Specify, make sure to:

  • Search on GitHub for the issue to see if it already exists

  • Try to recreate the issue in multiple locations (e.g. if you have a tree issue, try recreating in other trees)

    • Try to identify if it is a component issue (e.g. an issue with a query combo box not searching) rather than describing a specific case

      • Problem: Query combo box search is not functional anywhere in the application

        • Good Title: Query combo box search is not working

        • Bad Title: Can’t search on determination form

    • Include cases where it does not happen (e.g. happens in chronostrat tree, not in geography tree)

    • Think about these questions:

      • Is this happening in the latest tagged release (v7)?

      • Does this happen in any discipline?

      • Does this happen in multiple databases?

      • Does this happen anywhere else?

      • Try using different datasets, inputs, or sequences to see if the bug behaves differently.

  • If you suspect there may be two issues, please split them into separate issues

    • Keep bugs small in scope to simplify the process of resolving them.

Always Recreate On Older Versions

  • When reporting an issue on the production branch, or any development version of Specify, you must try to recreate the issue on the latest tagged release (v7) and plainly indicate if it does not occur there, indicating a regression.

  • For developers, tips to narrow down the origin of an issue. (Facultative)
    Find out when the bug has started (test previous versions), find when a bug appeared (someone please make a video)

    • Try to identify the PR that introduced the issue (instructions for this)

    • Steps to Identify the Commit That Introduced a Bug

  1. Open the Repository

    1. Navigate to the Sp7 repository on GitHub.

  2. View Commit History

    1. Click on the Commits tab to see the commit history.

  3. Filter Commits by Date

    1. Use the date filters to narrow down commits between:

      1. The date of the last release (before the bug appeared).

      2. The date the issue was reported or created.

  4. Start Reviewing Commits

    1. Scroll to the last page of the filtered commit list to begin with the oldest commits in the range.

  5. Identify Merge Commits

    1. Look for merge commits with the format: Merge pull request #1234 from specify/issue-3451

    2. These commits represent merged pull requests that may have introduced the bug.

  6. Copy the Full Commit SHA

    1. For each merge commit, copy the full SHA (a long alphanumeric string) for reference.

  7. Pull the Commit Locally

    1. Checkout the commit locally in your development environment using: git checkout <commit-SHA>

  8. Test the Application

    1. Launch your app from this commit and test for the bug.

  9. Determine Bug Presence

    1. If the bug is not present:

      1. Repeat the steps for the next merge commit.

    2. If the bug is present:

      1. Note down the issue number from the merge commit (e.g., issue-3451).

  10. Document Findings

    1. Write the name or number of the issue that introduced the bug into a new issue or bug report for tracking and resolution.

    Tips for Efficiency

    • Use git log locally: Instead of GitHub’s interface, you can filter commits directly in your terminal: git log –after=”YYYY-MM-DD” –before=”YYYY-MM-DD” –merges

    • Checkout a version of specify you suspect or know does not have the bug

    • You can checkout a specific tag (i.e., released version of Specify 7) by `git checkout tags/<tag_name>`. For example, `git checkout tags/v7.9.6.2`

Feature Request Guidelines

Feature requests are largely free-form and do not have strict guidelines, but please make sure to follow the template. Always include the name of the requesting institution and provide as much information as possible.