|
| 1 | +# Update Changelog |
| 2 | + |
| 3 | +You are helping to add an entry to the CHANGELOG.md file for the React on Rails project. |
| 4 | + |
| 5 | +## Critical Requirements |
| 6 | + |
| 7 | +1. **User-visible changes only**: Only add changelog entries for user-visible changes: |
| 8 | + |
| 9 | + - New features |
| 10 | + - Bug fixes |
| 11 | + - Breaking changes |
| 12 | + - Deprecations |
| 13 | + - Performance improvements |
| 14 | + - Security fixes |
| 15 | + - Changes to public APIs or configuration options |
| 16 | + |
| 17 | +2. **Do NOT add entries for**: |
| 18 | + - Linting fixes |
| 19 | + - Code formatting |
| 20 | + - Internal refactoring |
| 21 | + - Test updates |
| 22 | + - Documentation fixes (unless they fix incorrect docs about behavior) |
| 23 | + - CI/CD changes |
| 24 | + |
| 25 | +## Formatting Requirements |
| 26 | + |
| 27 | +### Entry Format |
| 28 | + |
| 29 | +Each changelog entry MUST follow this exact format: |
| 30 | + |
| 31 | +```markdown |
| 32 | +- **Bold description of change**. [PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [username](https://github.com/username). Optional additional context or details. |
| 33 | +``` |
| 34 | + |
| 35 | +**Important formatting rules**: |
| 36 | + |
| 37 | +- Start with a dash and space: `- ` |
| 38 | +- Use **bold** for the main description |
| 39 | +- End the bold description with a period before the link |
| 40 | +- Always link to the PR: `[PR 1818](https://github.com/shakacode/react_on_rails/pull/1818)` - **NO hash symbol** |
| 41 | +- Always link to the author: `by [username](https://github.com/username)` |
| 42 | +- End with a period after the author link |
| 43 | +- Additional details can be added after the main entry, using proper indentation for multi-line entries |
| 44 | + |
| 45 | +### Breaking Changes Format |
| 46 | + |
| 47 | +For breaking changes, use this format: |
| 48 | + |
| 49 | +```markdown |
| 50 | +- **Feature Name**: Description of the breaking change. See migration guide below. [PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [username](https://github.com/username). |
| 51 | + |
| 52 | +**Migration Guide:** |
| 53 | + |
| 54 | +1. Step one |
| 55 | +2. Step two |
| 56 | +``` |
| 57 | + |
| 58 | +### Category Organization |
| 59 | + |
| 60 | +Entries should be organized under these section headings. The project uses both standard and custom headings: |
| 61 | + |
| 62 | +**Standard headings** (from keepachangelog.com) - use these for most changes: |
| 63 | + |
| 64 | +- `#### Added` - New features |
| 65 | +- `#### Changed` - Changes to existing functionality |
| 66 | +- `#### Deprecated` - Deprecation notices |
| 67 | +- `#### Removed` - Removed features |
| 68 | +- `#### Fixed` - Bug fixes |
| 69 | +- `#### Security` - Security-related changes |
| 70 | +- `#### Improved` - Improvements to existing features |
| 71 | + |
| 72 | +**Custom headings** (project-specific) - use sparingly when standard headings don't fit: |
| 73 | + |
| 74 | +- `#### Breaking Changes` - Breaking changes with migration guides |
| 75 | +- `#### API Improvements` - API changes and improvements |
| 76 | +- `#### Developer Experience` - Developer workflow improvements |
| 77 | +- `#### Generator Improvements` - Generator-specific changes |
| 78 | +- `#### Performance` - Performance improvements |
| 79 | +- `#### Pro License Features` - React on Rails Pro features |
| 80 | + |
| 81 | +**Prefer standard headings.** Only use custom headings when the change needs more specific categorization. |
| 82 | + |
| 83 | +**Only include section headings that have entries.** |
| 84 | + |
| 85 | +### Version Management |
| 86 | + |
| 87 | +After adding entries, use the rake task to manage version headers: |
| 88 | + |
| 89 | +```bash |
| 90 | +bundle exec rake update_changelog |
| 91 | +``` |
| 92 | + |
| 93 | +This will: |
| 94 | + |
| 95 | +- Add headers for the new version |
| 96 | +- Update version diff links at the bottom of the file |
| 97 | + |
| 98 | +## Process |
| 99 | + |
| 100 | +### For Regular Changelog Updates |
| 101 | + |
| 102 | +1. **Determine the correct version tag to compare against**: |
| 103 | + |
| 104 | + - First, check the tag dates: `git log --tags --simplify-by-decoration --pretty="format:%ai %d" | head -10` |
| 105 | + - Find the latest version tag and its date |
| 106 | + - Compare main branch date to the tag date |
| 107 | + - If the tag is NEWER than main, it means main needs to be updated to include the tag's commits |
| 108 | + - **CRITICAL**: Always use `git log TAG..BRANCH` to find commits that are in the tag but not in the branch, as the tag may be ahead |
| 109 | + |
| 110 | +2. **Check commits and version boundaries**: |
| 111 | + |
| 112 | + - Run `git log --oneline LAST_TAG..master` to see commits since the last release |
| 113 | + - Also check `git log --oneline master..LAST_TAG` to see if the tag is ahead of master |
| 114 | + - If the tag is ahead, entries in "Unreleased" section may actually belong to that tagged version |
| 115 | + - Identify which commits contain user-visible changes |
| 116 | + - Extract PR numbers and author information from commit messages |
| 117 | + - **Never ask the user for PR details** - get them from the git history |
| 118 | + |
| 119 | +3. **Validate** that changes are user-visible (per the criteria above). If not user-visible, skip those commits. |
| 120 | + |
| 121 | +4. **Read the current CHANGELOG.md** to understand the existing structure and formatting. |
| 122 | + |
| 123 | +5. **Determine where entries should go**: |
| 124 | + |
| 125 | + - If the latest version tag is NEWER than master branch, move entries from "Unreleased" to that version section |
| 126 | + - If master is ahead of the latest tag, add new entries to "Unreleased" |
| 127 | + - Always verify the version date in CHANGELOG.md matches the actual tag date |
| 128 | + |
| 129 | +6. **Add or move entries** to the appropriate section under appropriate category headings. |
| 130 | + |
| 131 | + - **CRITICAL**: When moving entries from "Unreleased" to a version section, merge them with existing entries under the same category heading |
| 132 | + - **NEVER create duplicate section headings** (e.g., don't create two "### Fixed" sections) |
| 133 | + - If the version section already has a category heading (e.g., "### Fixed"), add the moved entries to that existing section |
| 134 | + - Maintain the category order as defined above |
| 135 | + |
| 136 | +7. **Verify formatting**: |
| 137 | + |
| 138 | + - Bold description with period |
| 139 | + - Proper PR link (NO hash symbol) |
| 140 | + - Proper author link |
| 141 | + - Consistent with existing entries |
| 142 | + - File ends with a newline character |
| 143 | + |
| 144 | +8. **Run linting** after making changes: |
| 145 | + |
| 146 | + ```bash |
| 147 | + bundle exec rubocop |
| 148 | + yarn run lint |
| 149 | + ``` |
| 150 | + |
| 151 | +9. **Show the user** the added or moved entries and explain what was done. |
| 152 | + |
| 153 | +### For Beta to Non-Beta Version Release |
| 154 | + |
| 155 | +When releasing from beta to a stable version (e.g., v16.1.0-beta.3 → v16.1.0): |
| 156 | + |
| 157 | +1. **Remove all beta version labels** from the changelog: |
| 158 | + |
| 159 | + - Change `### [v16.1.0-beta.1]`, `### [v16.1.0-beta.2]`, etc. to a single `### [v16.1.0]` section |
| 160 | + - Combine all beta entries into the stable release section |
| 161 | + |
| 162 | +2. **Consolidate duplicate entries**: |
| 163 | + |
| 164 | + - If bug fixes or changes were made to features introduced in earlier betas, keep only the final state |
| 165 | + - Remove redundant changelog entries for fixes to beta features |
| 166 | + - Keep the most recent/accurate description of each change |
| 167 | + |
| 168 | +3. **Update version diff links** using `bundle exec rake update_changelog` |
| 169 | + |
| 170 | +### For New Beta Version Release |
| 171 | + |
| 172 | +When creating a new beta version, ask the user which approach to take: |
| 173 | + |
| 174 | +**Option 1: Process changes since last beta** |
| 175 | + |
| 176 | +- Only add entries for commits since the previous beta version |
| 177 | +- Maintains detailed history of what changed in each beta |
| 178 | + |
| 179 | +**Option 2: Collapse all prior betas into current beta** |
| 180 | + |
| 181 | +- Combine all beta changelog entries into the new beta version |
| 182 | +- Removes previous beta version sections |
| 183 | +- Cleaner changelog with less version noise |
| 184 | + |
| 185 | +After the user chooses, proceed with that approach. |
| 186 | + |
| 187 | +## Examples |
| 188 | + |
| 189 | +Run this command to see real formatting examples from the codebase: |
| 190 | + |
| 191 | +```bash |
| 192 | +grep -A 3 "^#### " CHANGELOG.md | head -30 |
| 193 | +``` |
| 194 | + |
| 195 | +### Good Entry Example |
| 196 | + |
| 197 | +```markdown |
| 198 | +- **Attribution Comment**: Added HTML comment attribution to Rails views containing React on Rails functionality. The comment automatically displays which version is in use (open source React on Rails or React on Rails Pro) and, for Pro users, shows the license status. This helps identify React on Rails usage across your application. [PR 1857](https://github.com/shakacode/react_on_rails/pull/1857) by [AbanoubGhadban](https://github.com/AbanoubGhadban). |
| 199 | +``` |
| 200 | + |
| 201 | +### Entry with Sub-bullets Example |
| 202 | + |
| 203 | +```markdown |
| 204 | +- **Server Bundle Security**: Added new configuration options for enhanced server bundle security and organization: |
| 205 | + - `server_bundle_output_path`: Configurable directory (relative to the Rails root) for server bundle output (default: "ssr-generated"). If set to `nil`, the server bundle will be loaded from the same public directory as client bundles. [PR 1798](https://github.com/shakacode/react_on_rails/pull/1798) by [justin808](https://github.com/justin808) |
| 206 | + - `enforce_private_server_bundles`: When enabled, ensures server bundles are only loaded from private directories outside the public folder (default: false for backward compatibility) [PR 1798](https://github.com/shakacode/react_on_rails/pull/1798) by [justin808](https://github.com/justin808) |
| 207 | +``` |
| 208 | + |
| 209 | +### Breaking Change Example |
| 210 | + |
| 211 | +```markdown |
| 212 | +- **React on Rails Core Package**: Several Pro-only methods have been removed from the core package and are now exclusively available in the `react-on-rails-pro` package. If you're using any of the following methods, you'll need to migrate to React on Rails Pro: |
| 213 | + - `getOrWaitForComponent()` |
| 214 | + - `getOrWaitForStore()` |
| 215 | + - `getOrWaitForStoreGenerator()` |
| 216 | + - `reactOnRailsStoreLoaded()` |
| 217 | + - `streamServerRenderedReactComponent()` |
| 218 | + - `serverRenderRSCReactComponent()` |
| 219 | + |
| 220 | +**Migration Guide:** |
| 221 | + |
| 222 | +To migrate to React on Rails Pro: |
| 223 | + |
| 224 | +1. Install the Pro package: |
| 225 | + yarn add react-on-rails-pro |
| 226 | + |
| 227 | +2. Update your imports from `react-on-rails` to `react-on-rails-pro`: |
| 228 | + // Before |
| 229 | + import ReactOnRails from 'react-on-rails'; |
| 230 | + |
| 231 | + // After |
| 232 | + import ReactOnRails from 'react-on-rails-pro'; |
| 233 | +``` |
| 234 | + |
| 235 | +## Additional Notes |
| 236 | + |
| 237 | +- Keep descriptions concise but informative |
| 238 | +- Focus on the "what" and "why", not the "how" |
| 239 | +- Use past tense for the description |
| 240 | +- Be consistent with existing formatting in the changelog |
| 241 | +- Always ensure the file ends with a trailing newline |
| 242 | +- See CHANGELOG.md lines 15-18 for additional contributor guidelines |
0 commit comments