Contributing Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• CONTRIBUTING-old.md
• public/js/msa/README.md
• public/js/p3/widget/app/AppBase.js
• public/js/p3/widget/ReportProblem.js

The Contributing Guidelines for the BV-BRC (DXKB) Web Application establish the standardized procedures for code commits, environment configuration, and development workflows. These guidelines ensure that contributions—whether features, bug fixes, or documentation updates—maintain project quality, consistency, and stability across production and development environments.

The project emphasizes modularity, simplicity, and rigorous testing. Developers are encouraged to follow established branching strategies and coding conventions to facilitate efficient peer reviews and automated deployment processes.
Sources: CONTRIBUTING-old.md:1-10, public/js/msa/README.md:225-235

Developer Environment Setup

First-time contributors must configure their local Git environment to synchronize with the project's upstream repository. The project utilizes npm for package management and gulp for build automation.

Git Configuration

1. Fork the repository on GitHub.
2. Clone the fork locally.
3. Configure Upstream:

   git remote add upstream https://github.com/BV-BRC/bvbrc_website.git
   

4. Synchronize:

   git checkout develop
   git fetch upstream
   git pull upstream develop
   

Sources: CONTRIBUTING-old.md:12-30

Build and Watch System

The development environment relies on node and npm. Key commands include:

• npm install: Installs dependencies and validates the installation by executing a build and running unit tests.
• npm run watch: Utilizes watchify to recompile JavaScript to the build folder automatically upon file changes.
• gulp build: Regenerates CSS and JS with minimization via Browserify.
  Sources: public/js/msa/README.md:245-285

Branching Strategy

The repository follows a multi-tier branching model to isolate production-ready code from work-in-progress features.

Branch	Purpose	Target Environment
master	Production release and critical bug fixes.	https://www.bv-brc.org
develop	Release preparation and integrated features.	https://beta.bv-brc.org
preview	Work-in-progress; merged feature branches for internal review.	https://alpha.bv-brc.org
features/*	New feature development; always branches from develop.	Local / Feature-specific

Sources: CONTRIBUTING-old.md:40-55

Branching Flow Diagram

The following diagram illustrates the relationship between operational branches and the deployment lifecycle.

The diagram shows the promotion of code from feature branches through testing environments to production.
Sources: CONTRIBUTING-old.md:40-65

Development Workflow

The recommended process for adding code depends on the nature of the change.

Feature Development

1. Create a branch from develop using the prefix features/ (e.g., features/workspace2.0).
2. Send a Pull Request (PR) to the branch of the same name for internal review in the preview branch.
3. Once validated, the maintainer merges the code into develop.
4. Delete the feature branch post-merge.

Bug and Hot Fixes

• Bug Fixes: PRs should be directed to the develop branch and include issue tags (e.g., resolves BV-BRC/issues#123).
• Hot Fixes: Urgent production issues require PRs to both develop and master simultaneously.
  Sources: CONTRIBUTING-old.md:60-85

Coding Standards

Adhering to code conventions ensures the codebase remains maintainable and reviewable.

General Principles

• KISS (Keep It Simple, Stupid): Avoid unnecessary complexity in logic and architecture.
• Modularity: Components should be self-contained and reusable.
• Method Signatures: Public methods should ideally accept no more than two arguments; dictionaries are preferred for flexibility.
• File Length: Limit files to a maximum of 200 lines to encourage better organization.
• Linting: Developers must lint code to maintain conventions. Pre-commit hooks are recommended.
  Sources: CONTRIBUTING-old.md:32-38, public/js/msa/README.md:225-240

App and Widget Architecture

New features should extend the AppBase class, which provides common JSON parameters and validation logic.

Parameter	Description
target_genome_id	The reference genome for the service.
strategy	Controls the workflow or algorithm (e.g., 'recipe').
output_path	Location in the workspace for results.
requireAuth	Boolean flag indicating if the widget requires user login.

Sources: public/js/p3/widget/app/AppBase.js:30-50

Testing and Quality Assurance

Testing is categorized into unit tests and browser-based tests.

Test Suites

• Unit Tests (test/mocha): Logic tests that do not require DOM interaction. These are executed via npm test or gulp test.
• Headless Browser Tests (test/phantom): Tests requiring DOM interaction.
• Debugging: Developers can open tests/index.html in a browser to set breakpoints. Note that CoffeeScript must be compiled to all_tests.js before browser execution.
  Sources: public/js/msa/README.md:290-330

Problem Reporting

The contribution cycle includes feedback from users and developers via the ReportProblem widget. Reports are sent to the /reportProblem endpoint and include system state data to facilitate debugging.

Problem Report Data Flow

The diagram outlines the data collection and submission process for reporting software issues.
Sources: public/js/p3/widget/ReportProblem.js:15-60

Preparing a Release

When code in develop is ready for production:

1. Increment the version in ./package.json following semantic versioning.
2. Commit the build changes.
3. Deploy the build, which updates the version displayed in the User Interface.
   Sources: CONTRIBUTING-old.md:95-105

Contribution guidelines are designed to streamline the growth of the project while maintaining high architectural standards. By following these setup, branching, and testing procedures, developers contribute to a robust ecosystem for bioinformatic analysis.