Skip to content

docs: adds guidelines for contributors #419

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jun 18, 2025
Merged

docs: adds guidelines for contributors #419

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
73f5a6a
commit guidelines
latin-panda May 22, 2025
f48f59a
Merge branch 'main' of https://github.com/getodk/web-forms into commi…
latin-panda Jun 17, 2025
c81f8c7
Adds to contributor guidelines
latin-panda Jun 17, 2025
b5ffd8e
Allows rebuild cache for deps and build
latin-panda Jun 17, 2025
360883a
reverts: Allows rebuild cache for deps and build
latin-panda Jun 17, 2025
d7fad03
Take 1 - no fail-on-cache-miss
latin-panda Jun 18, 2025
2925a36
Take 2 - no fail-on-cache-miss
latin-panda Jun 18, 2025
d8b01be
revert take-1 and take 2
latin-panda Jun 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -424,3 +424,55 @@ If you'd like to try the functionality available on `main`, see the preview [on
1. Verify that the changelogs look good, commit changes, open a PR, merge the PR
1. Push tags for each package in the format `[email protected]`. A Github action will publish the packages on NPM
1. Update dependencies to kick off the new release cycle. We do this so that dependency updates get verified implicitly during development.

## Contributing to the project

Thank you for your interest in contributing! This section outlines guidelines to ensure smooth collaboration and maintainable code.

### Commit message guidelines

We use a standardized commit message format inspired by [Conventional Commits](https://www.conventionalcommits.org/) to enable automated releases and maintain clear project history. The format is:

```
<type>(<issue>): <description>

<optional body with details>

<optional footer, e.g., BREAKING CHANGE or Co-authored-by>
```

- **Type**: Use `feat`, `fix`, `docs`, `test`, `chore`, or `perf`.
- **Issue**: Reference the ticket/issue (e.g., `#33`).
- **Description**: Concise (≤50 chars), present tense, lowercase (e.g., `add geopoint input component`).
- **Body**: Optional, lists specific changes (e.g., `- add geopoint.xml demo form`).
- **Footer**: Use `Co-authored-by: @<username>` or `BREAKING CHANGE:` for automation.

Our commit message format enables automated release management. This standard ensures commits are categorized to trigger appropriate version bumps:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All of this is managed by changeset so this section doesn't feel relevant. Changeset makes sense in our context because the version bumps aren't always the same across packages.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you see a benefit in having a format for commit messages?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find that prefixes make the commit history easier to understand and scan visually. But I may be biased from using them for years

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be interesting to tag and publish the packages when the prep PR is merged, based on a commit:

release: pack version and publish

Copy link
Collaborator Author

@latin-panda latin-panda May 22, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note to myself - try this out later:

name: Tag packages for release

on:
  pull_request:
    types: [closed]
    branches:
      - main

jobs:
  tag-packages:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      # Checkout the repository with full history
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          # Use a Personal Access Token to push tags (required for protected branches)
          token: ${{ secrets.PAT }}

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Check commit message
        id: check_commit
        run: |
          COMMIT_MESSAGE=$(git log --pretty=%B -1 ${{ github.event.pull_request.merge_commit_sha }})
          echo "Commit message: $COMMIT_MESSAGE"
          if echo "$COMMIT_MESSAGE" | grep -q "^release:"; then
            echo "Release commit detected"
            echo "is_release=true" >> $GITHUB_OUTPUT
          else
            echo "No release commit detected"
            echo "is_release=false" >> $GITHUB_OUTPUT
          fi

      - name: Configure git
        if: steps.check_commit.outputs.is_release == 'true'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Tag packages
        if: steps.check_commit.outputs.is_release == 'true'
        run: |
          # Array of package directories
          PACKAGES=(
            "packages/web-forms"
            "packages/xforms-engine"
            "packages/xpath"
            "packages/tree-sitter-xpath"
          )

          for PKG in "${PACKAGES[@]}"; do
            NAME=$(node -p "require('./$PKG/package.json').name")
            VERSION=$(node -p "require('./$PKG/package.json').version")
            TAG="$NAME@$VERSION"

            if git tag | grep -Fx "$TAG"; then
              echo "Tag $TAG already exists, skipping..."
            else
              echo "Creating tag $TAG for $NAME"
              git tag "$TAG"
            fi
          done

          # Push all new tags
          git push origin --tags

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't mind the prefixes and happy to follow your lead there as long as we keep changeset for versioning and changelog management for now. I like the future idea of automating tag and release!


- **Feature Commits (`feat`)**: Introduce new functionality and result in a **minor** version bump (e.g., `1.2.3` → `1.3.0`).
- **Fix Commits (`fix`)**: Address bugs and trigger a **patch** version bump (e.g., `1.2.3` → `1.2.4`).
- **Non-Releasing Commits (`test`, `docs`)**: Improve code quality or documentation without affecting production code, so they don’t trigger a release.
- **Chore Commits (`chore`)**: Handle maintenance tasks (e.g., dependency updates) and trigger a **patch** release.
- **Breaking Changes**: Marked with `BREAKING CHANGE:` in the footer, these trigger a **major** version bump (e.g., `1.2.3` → `2.0.0`). Example: Changing the component library to another one.

This structure ensures that only meaningful changes (features, fixes, or breaking changes) drive releases, while tests or chores are excluded or minimized, keeping our versioning predictable and automated changelogs clear.

**Example Commit**:
```
feat(#33): add input and readonly components

- Implement geopoint input component in Vue client
- Add XPath evaluator for geopoint

Co-authored-by: @jane_doe and @tom_smith
```

This commit triggers a **minor** release because it’s a `feat`, includes a clear description, credits contributors (@jane_doe, @john_smith), and links to issue #33 for traceability.

### Other Guidelines

- **Code Style**: Follow the project's linting rules (e.g., ESLint, Prettier).
- **Testing**: Include tests for new features or bug fixes.
- **Pull Requests**: Reference related issues and describe changes clearly.

For questions, reach out to the maintainers. Happy contributing!
Loading