feat: Add CHANGELOG system with Keep a Changelog format and CI enforc…

.github/workflows/changelog-check.yml

@@ -0,0 +1,112 @@
+name: Changelog Check
+
+on:
+  pull_request:
+    paths:
+      - 'contracts/**'
+      - 'crates/**'
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  changelog:
+    name: Verify CHANGELOG.md updated
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check if CHANGELOG.md was modified
+        id: changelog_check
+        run: |
+          # Get the base commit (main branch or merge base)
+          BASE="${{ github.event.pull_request.base.sha || github.event.before }}"
+
+          # If we can't determine base, use the previous commit
+          if ! git cat-file -e "${BASE}^{commit}" 2>/dev/null; then
+            BASE="$(git rev-parse HEAD^)"
+          fi
+
+          # Check if CHANGELOG.md was modified in this PR
+          if git diff --name-only "${BASE}...HEAD" | grep -q "^CHANGELOG.md$"; then
+            echo "CHANGELOG_UPDATED=true" >> "$GITHUB_OUTPUT"
+            echo "✓ CHANGELOG.md was updated"
+          else
+            echo "CHANGELOG_UPDATED=false" >> "$GITHUB_OUTPUT"
+            echo "✗ CHANGELOG.md was NOT updated"
+          fi
+
+      - name: Check if Unreleased section has entries
+        id: unreleased_check
+        if: steps.changelog_check.outputs.CHANGELOG_UPDATED == 'true'
+        run: |
+          # Extract the Unreleased section and check if it has meaningful content
+          UNRELEASED_SECTION=$(sed -n '/^## \[Unreleased\]/,/^## \[/p' CHANGELOG.md | head -n -1)
+
+          # Count lines that are actual content (not empty, not headers, not subsection headers)
+          CONTENT_LINES=$(echo "$UNRELEASED_SECTION" | grep -E "^(### |[^ #-]|-)" | grep -v "^###" | wc -l)
+
+          if [ "$CONTENT_LINES" -gt 0 ]; then
+            echo "HAS_ENTRIES=true" >> "$GITHUB_OUTPUT"
+            echo "✓ Unreleased section has entries"
+          else
+            echo "HAS_ENTRIES=false" >> "$GITHUB_OUTPUT"
+            echo "⚠ Unreleased section appears empty"
+          fi
+
+      - name: Validate changelog format
+        if: steps.changelog_check.outputs.CHANGELOG_UPDATED == 'true'
+        run: |
+          # Verify CHANGELOG.md follows Keep a Changelog format
+          if head -n 20 CHANGELOG.md | grep -q "based on \[Keep a Changelog\]"; then
+            echo "✓ CHANGELOG.md format is valid"
+          else
+            echo "✗ CHANGELOG.md does not reference Keep a Changelog format"
+            exit 1
+          fi
+
+      - name: Require CHANGELOG.md update
+        if: steps.changelog_check.outputs.CHANGELOG_UPDATED == 'false'
+        run: |
+          echo "::error::CHANGELOG.md must be updated for PRs that modify contract or core code."
+          echo ""
+          echo "This PR modifies files in 'contracts/' or 'crates/' directories."
+          echo "Please update CHANGELOG.md with your changes in the [Unreleased] section."
+          echo ""
+          echo "Guidelines:"
+          echo "- Use appropriate subsections: Added, Changed, Deprecated, Removed, Fixed, Security"
+          echo "- Be descriptive about what changed and why"
+          echo "- Group changes by contract when relevant"
+          echo "- Reference GitHub issues or PRs when applicable"
+          echo ""
+          echo "See CHANGELOG.md for more details and examples."
+          exit 1
+
+      - name: Comment on PR if missing changelog
+        if: failure() && steps.changelog_check.outputs.CHANGELOG_UPDATED == 'false'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '⚠️ **CHANGELOG.md Update Required**\n\n' +
+                    'This PR modifies contract or core code but does not update CHANGELOG.md.\n\n' +
+                    'Please add an entry to the [Unreleased] section describing your changes. Use these guidelines:\n\n' +
+                    '- **Added**: for new features or contracts\n' +
+                    '- **Changed**: for changes in existing functionality\n' +
+                    '- **Deprecated**: for soon-to-be removed features\n' +
+                    '- **Removed**: for now removed features\n' +
+                    '- **Fixed**: for any bug fixes\n' +
+                    '- **Security**: for security-related fixes\n\n' +
+                    'Example:\n' +
+                    '```markdown\n' +
+                    '### Fixed\n' +
+                    '- **markets**: Corrected fee calculation in place_bet (#' + context.issue.number + ')\n' +
+                    '```\n\n' +
+                    'See [CHANGELOG.md](https://github.com/' + context.repo.owner + '/' + context.repo.repo + '/blob/main/CHANGELOG.md) for more details.'
+            })

CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial CHANGELOG.md following Keep a Changelog format
+- CI check requiring CHANGELOG.md updates for PRs modifying contract code
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## Project Overview
+
+This monorepo contains Stellar smart contracts for a decentralized prediction market system. Changes are organized by contract and category (Added, Changed, Deprecated, Removed, Fixed, Security).
+
+### Contracts
+
+- **admin** - Administrative contract for system governance
+- **allowlist** - Contract for managing access control and allowlists
+- **analytics** - Analytics and reporting contract
+- **auction** - Auction mechanism contract
+- **betting** - Betting functionality contract
+- **disputes** - Dispute resolution contract
+- **fees** - Fee management contract
+- **markets** - Core markets contract
+- **migrate** - Contract migration utilities
+- **monitor** - Monitoring contract
+- **oracles** - Oracle price feeds
+- **predictify-hybrid** - Hybrid prediction contract
+- **reporting** - Reporting contract
+- **resolution** - Resolution contract
+- **validators** - Validator contract
+- **analytics** - Analytics contract
+
+### Guidelines for Contributors
+
+When adding changes to this CHANGELOG:
+
+1. **Add entries to the [Unreleased] section** before the PR is merged
+2. **Use appropriate subsections**: Added, Changed, Deprecated, Removed, Fixed, Security
+3. **Be descriptive**: Explain what changed and why, not just "bug fix"
+4. **Group by contract**: When describing changes, indicate which contract(s) are affected
+5. **Link to issues/PRs**: Reference GitHub issues or PRs when relevant
+
+Example entry:
+```
+### Added
+- **markets**: New oracle price feed validation in `submit_oracle_outcome` (#1234)
+- **disputes**: Support for multi-validator dispute resolution
+
+### Fixed
+- **fees**: Corrected fee calculation overflow on large amounts (#1235)
+- **betting**: Fixed race condition in bet placement under high concurrency
+```
+
+### Release Process
+
+When creating a new release:
+
+1. Create a new section with the version and date: `## [X.Y.Z] - YYYY-MM-DD`
+2. Move all entries from [Unreleased] to the new section
+3. Add a footer link at the bottom of the file
+4. Tag the release in git
+5. Create a GitHub release using the CHANGELOG entries
+
+### Version Links
+
+[Unreleased]: https://github.com/your-org/hermes/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/your-org/hermes/releases/tag/v0.0.1

CONTRIBUTING.md

@@ -50,5 +50,32 @@ code means the deployed contract does not match the local build.
 - Keep PRs focused on a single concern.
 - All CI checks (tests + snapshot goldens) must pass before merge.
 - Do not push directly to `main`; open a pull request instead.
+- **For contract or core code changes, update CHANGELOG.md** in the `[Unreleased]` section describing your changes
 - For contract changes, run `verify_contract_sync.sh` post-deploy and attach
   the output to your PR description.
+
+## Updating the Changelog
+
+If your PR modifies code in `contracts/` or `crates/`, you must update `CHANGELOG.md`:
+
+1. Open `CHANGELOG.md` and locate the `[Unreleased]` section
+2. Add your changes under the appropriate subsection:
+   - **Added**: New features or contracts
+   - **Changed**: Changes to existing functionality
+   - **Deprecated**: Features being phased out
+   - **Removed**: Removed features
+   - **Fixed**: Bug fixes
+   - **Security**: Security-related changes
+3. Be descriptive and indicate which contract(s) are affected
+
+Example:
+```markdown
+### Fixed
+- **markets**: Corrected fee calculation in `place_bet` (#1234)
+- **disputes**: Fixed race condition in dispute resolution
+
+### Added
+- **validators**: New validator eligibility check in initialization
+```
+
+See [Keep a Changelog](https://keepachangelog.com/) for detailed guidelines on formatting.

docs/CHANGELOG_COMMIT_MESSAGE.md

@@ -0,0 +1,55 @@
+# Suggested Commit Message for CHANGELOG Implementation
+
+Use this as a template when committing the CHANGELOG implementation:
+
+```
+feat: Add CHANGELOG.md with Keep a Changelog format and CI enforcement
+
+This implements a comprehensive changelog system for the Hermes project to
+provide transparency on contract changes across releases.
+
+Changes:
+- CHANGELOG.md: Main changelog following Keep a Changelog 1.0.0 format
+  - [Unreleased] section for tracking ongoing changes
+  - All 20 Hermes contracts documented and categorized
+  - Contributor guidelines and release process documentation
+
+- .github/workflows/changelog-check.yml: New CI workflow
+  - Requires CHANGELOG.md to be updated for PRs modifying contracts/ or crates/
+  - Validates Unreleased section has meaningful entries
+  - Confirms adherence to Keep a Changelog format
+  - Auto-comments on PRs with guidance if requirements unmet
+
+- Documentation suite in docs/:
+  - CHANGELOG_QUICK_REFERENCE.md: Quick how-to for developers
+  - CHANGELOG_TEMPLATE.md: Detailed templates and examples
+  - CHANGELOG_IMPLEMENTATION.md: Technical architecture details
+
+- CONTRIBUTING.md: Added "Updating the Changelog" section
+  - Step-by-step instructions for contributors
+  - Integrated with existing PR guidelines
+
+Benefits:
+- Users can now see what changed between versions
+- Automated CI check ensures release notes are never forgotten
+- Multiple documentation levels for different user needs
+- Clear, standard format following Keep a Changelog convention
+- Release process fully documented
+
+Fixes: #XXXX (reference the issue this closes)
+```
+
+## Alternative Shorter Version
+
+```
+feat: Add CHANGELOG tracking system with CI enforcement
+
+- Create CHANGELOG.md following Keep a Changelog 1.0.0
+- Add CI workflow (changelog-check.yml) requiring updates for contract changes
+- Add comprehensive documentation in docs/
+- Update CONTRIBUTING.md with changelog guidelines
+```
+
+## For Squash Merges
+
+If the PR is squashed before merge, use the longer version above. This preserves the full context of the implementation.