Contributing Guidelines

Relevant source files

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

• package.json
• features/step_definitions/web_steps.rb
• spec/spec_helper.rb
• spec/rails_helper.rb
• features/support/env.rb
• babel.config.js
• spec/linters/eslint_spec.rb
• config/webpacker.yml

Introduction

Actionmap is a Ruby on Rails application designed to connect users with their political representatives and local events. Contributing to this project requires adherence to established coding standards, testing protocols, and dependency management practices. These guidelines ensure that the codebase remains maintainable, scalable, and robust across different development environments.

The project utilizes a modern stack including Rails for the backend and Webpacker/D3.js for the frontend. Contributors are expected to maintain high test coverage using RSpec and Cucumber while ensuring JavaScript code adheres to ESLint configurations.

Sources: README.md, package.json:10-35, config/webpacker.yml:4-10

Development Environment Setup

The project relies on specific versions of Node.js and Yarn to manage frontend assets and dependencies. Configuration for Babel and Webpacker is provided to ensure consistent compilation across development, test, and production environments.

Dependency Management

Frontend dependencies are managed through Yarn. Key packages include D3 for map visualizations and Bootstrap for styling.

Tool	Required Version	Purpose
Node.js	12.x or 14.x	JavaScript Runtime
Yarn	1.22.x	Package Management
Ruby	(Standard Rails environment)	Backend Logic

Sources: package.json:6-9, package.json:15-28

Environment Configuration

The application uses babel.config.js to handle JavaScript transpilation based on the NODE_ENV. It supports three primary environments:

• Development: Standard development features with source maps.
• Test: Configured for Node-based testing using babel-plugin-dynamic-import-node.
• Production: Optimized for performance with full transforms.

Sources: babel.config.js:2-20

Testing Standards

Actionmap maintains a rigorous testing suite divided into unit/integration tests (RSpec) and acceptance tests (Cucumber).

RSpec (Unit and Integration)

RSpec is used for testing Ruby logic. The configuration in spec/rails_helper.rb manages the test database state and external dependencies.

• Database Management: DatabaseCleaner is utilized to ensure a clean state between tests. The default strategy is :transaction, switching to :truncation for JavaScript-enabled tests.
• FactoryBot: Used for creating test data.
• SimpleCov: Automatically tracks code coverage; results should be reviewed before submission.

Sources: spec/rails_helper.rb:4-53, spec/spec_helper.rb:16-50

Cucumber (Acceptance Testing)

Cucumber tests are used to verify end-to-end user flows.

• Step Definitions: While web_steps.rb provides basic interactions (e.g., When I press "button"), contributors are encouraged to write higher-level, declarative steps to improve maintainability.
• JavaScript Strategy: Cucumber is configured to use :truncation for tests involving JavaScript to avoid threading issues.

Sources: features/step_definitions/web_steps.rb:1-15, features/support/env.rb:64-70

Test Execution Flow

The following diagram illustrates the lifecycle of a test run within the Actionmap environment.

This flow ensures that every test run starts with a clean environment and ends with updated coverage metrics.
Sources: spec/rails_helper.rb:34-53, features/support/env.rb:10-15

Linting and Code Quality

To maintain a consistent coding style, the project enforces linting for both JavaScript and Ruby.

JavaScript Linting

JavaScript files must pass ESLint checks based on the Airbnb Base configuration.

• Commands:
  • yarn run lint: Checks for offenses in app/**/*.js and config/**/*.js.
  • yarn run lint_fix: Automatically fixes fixable style issues.
• Validation: The eslint_spec.rb file ensures that the CI pipeline fails if any linting offenses exist.

Sources: package.json:37-40, spec/linters/eslint_spec.rb:5-12

Ruby Style

Ruby code should follow standard Rails conventions. The rails_helper.rb enforces schema maintenance, ensuring that the test database matches the current migrations before execution.

Sources: spec/rails_helper.rb:28-33

Frontend Assets and Webpacker

The project uses Webpacker to compile assets. Contributors adding new JavaScript features should place them in app/javascript/packs.

Webpacker Configuration

The config/webpacker.yml file defines how assets are compiled.

• Source Path: app/javascript
• Entry Points: packs
• Extensions: Supports .vue, .js, .sass, .scss, and various image formats.

Sources: config/webpacker.yml:4-20

Asset Compilation Flow

The following sequence diagram shows how Webpacker processes assets during development.

Contributors must ensure that bin/webpack-dev-server is running when making frequent frontend changes.
Sources: config/webpacker.yml:42-55, app/javascript/packs/application.js:1-10

Summary

Contributors to Actionmap must ensure their code is well-tested and adheres to the project's linting standards. By utilizing the provided RSpec and Cucumber configurations and following the Webpacker asset structure, developers can maintain the integrity of the application's representative tracking and news aggregation features.
Sources: README.md, package.json:5-45