Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
131 lines (87 loc) · 4.87 KB

CONTRIBUTING.md

File metadata and controls

131 lines (87 loc) · 4.87 KB
Raw

Contributing

Thanks for taking the time to contribute!

The following is a set of guidelines for contributing to monday_ruby. These are mostly guidelines, not rules. Use your best judgment, and feel to propose changes to this document in a pull request.

Your first code contribution

Unsure where to begin contributing? You can start by looking through good first issue and help wanted issues.

Pull request

Please follow these steps to have your contribution considered:

  1. Follow the pull request template.
  2. Follow the commit guidelines.
  3. After you submit your pull request, verify that all the status checks are passing.

Testing Guidelines

This project uses VCR to record HTTP interactions for tests. This means you do not need a Monday.com API token to run most tests or contribute to the project.

Running Tests

To run the test suite:

bundle exec rake spec

All tests will use pre-recorded VCR cassettes stored in spec/fixtures/vcr_cassettes/.

Working with VCR Cassettes

For most contributions, you won't need to modify VCR cassettes. The existing cassettes cover the current API functionality.

When You Need to Record New Cassettes

You only need to record new VCR cassettes when:

  • Adding support for a new API endpoint that doesn't have existing test coverage
  • Modifying an existing API call that changes the request/response structure

To record new cassettes:

  1. Set your Monday.com API token as an environment variable:

    export MONDAY_TOKEN="your_token_here"

  2. Delete the old cassette file (if updating an existing test):

    rm spec/fixtures/vcr_cassettes/your_cassette_name.yml

  3. Run the specific test to generate a new cassette:

    bundle exec rspec spec/path/to/your_spec.rb

  4. Important: Before committing, verify the cassette doesn't contain sensitive data:

    • VCR automatically filters the Authorization header
    • Check for any other sensitive information in the cassette file
    • Cassettes are committed to the repository

Testing New Features Without API Access

If you're adding a new feature but don't have API access to record cassettes:

  1. Write your implementation and tests
  2. Create a pull request noting that cassettes need to be recorded
  3. A maintainer with API access will record the cassettes for you

Code Quality

Run RuboCop to ensure code style compliance:

bundle exec rake rubocop

Documentation

The project uses Docyard to generate documentation from Markdown files. The documentation site is hosted at https://sanifhimani.github.io/monday_ruby/.

When to Update Documentation

Update documentation when you:

  • Add a new resource or method to the public API
  • Change the behavior of existing methods
  • Add new features or configuration options
  • Fix bugs that affect documented behavior

Documentation Structure

Documentation follows the Diataxis framework:

  • Getting Started (docs/getting-started/) - Learning-oriented, gets users started
  • Guides (docs/guides/) - Task-oriented, solves specific problems
  • Reference (docs/reference/) - Information-oriented, describes the API
  • Explanation (docs/explanation/) - Understanding-oriented, explains concepts

Adding/Updating Documentation

Documentation files are located in the docs/ directory. Navigation is configured in docs/_sidebar.yml.

Steps to Update Documentation:

  1. Find or create the appropriate file based on what you're documenting
  2. Follow the existing format - look at similar documentation files for examples
  3. Test your code examples - all examples should be runnable and accurate
  4. Update navigation if adding new pages - edit _sidebar.yml for the respective folder

Documentation Guidelines:

  • Code examples must be accurate - verify against VCR test fixtures or real API
  • Include practical examples - show real-world usage, not just syntax
  • Be consistent - follow the style and tone of existing documentation
  • No emojis - maintain professional tone in documentation
  • Link related pages - help users discover relevant documentation
  • Keep examples self-contained - users should be able to copy-paste and run

Deploying Documentation

Documentation is automatically deployed via GitHub Actions when changes are merged to the main branch. You don't need to manually deploy.

Commit message guidelines

  • Use present tense ("Add feature" not "Added feature")
  • Use the imperative mood ("Move file to..." not "Moves file to...")
  • Limit the first line to 70 characters or less.
  • Reference issues and pull requests after the first line.
  • Try to follow conventional commits