diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 4e8597e3..977c9a83 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -12,6 +12,6 @@ ## Suggestions on how to test this: -## Is there a release notes update needed for this change?: +## Is there a release notes or changelog update needed for this change?: ## Additional documentation: diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..32bb51b6 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,21 @@ +# Changelog + +All notable changes to **Dataverse Client Javascript** are documented here. + +This changelog follows the principles of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and adheres to [Semantic Versioning](https://semver.org/). This document is intended for developers, contributors, and users who need to understand the technical details. + +## [Unreleased] + +### Added + +### Changed + +### Fixed + +### Removed + +--- + +## [v2.0.0] -- 2025-07-04 + +[Unreleased]: https://github.com/IQSS/dataverse-frontend/compare/v2.0.0...develop diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 44a7f046..7e53e952 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,6 +16,29 @@ First of all thank you very much for your interest in contributing to this proje - Unit and integration tests pass - Unit and integration tests for new functionality/fix are added - Documentation is updated (Any new use case added or modified should be documented in the [Use Cases](./docs/useCases.md) section) +- Changelog is updated with your changes in the `[Unreleased]` section of [CHANGELOG.md](./CHANGELOG.md) + +## Maintaining the Changelog + +When contributing to this project, it's important to document your changes in the changelog to help users and developers understand what has been added, changed, fixed, or removed between versions. The changelog helps maintain transparency about project evolution and assists users in understanding the impact of updates. We also have another changelog for design system, so for any design system changes, please include them in that changelog. + +### When to Add Changelog Entries + +**Every pull request should include a changelog entry** + +Add a changelog entry for changes, including: + +- **Added**: New features, components, or functionality +- **Changed**: Changes to existing functionality, API modifications, or package updates +- **Fixed**: Bug fixes and issue resolutions +- **Removed**: Deprecated features or removed functionality + +### How to Add Changelog Entries + +1. **Add your changes to the `[Unreleased]` section** at the top of `CHANGELOG.md` +2. **Categorize your changes** under the appropriate category(Added, Changed, Fixed, Removed) +3. **Write clear, concise descriptions** that help users understand the impact of changes +4. **Include relevant issue numbers** when applicable ## Code of Conduct diff --git a/README.md b/README.md index 4421abdf..44b2266d 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,10 @@ For detailed information about available use cases see [Use Cases Docs](https:// For detailed information about usage see [Usage Docs](https://github.com/IQSS/dataverse-client-javascript/blob/main/docs/usage.md). +## Changelog + +See [CHANGELOG.md](https://github.com/IQSS/dataverse-client-javascript/blob/main/CHANGELOG.md) for a detailed history of changes to this project. + ## Contributing Want to add a new use case or improve an existing one? Please check the [Contributing](https://github.com/IQSS/dataverse-client-javascript/blob/main/CONTRIBUTING.md) section. diff --git a/docs/making-releases.md b/docs/making-releases.md index 13ed7d96..ce405014 100644 --- a/docs/making-releases.md +++ b/docs/making-releases.md @@ -4,6 +4,7 @@ - [Regular or Hotfix?](#regular-or-hotfix) - [Create Github Issue and Release Branch](#create-github-issue-and-release-branch) - [Update the version](#update-the-version) +- [Update the changelog](#update-the-changelog) - [Merge "release branch" into "main"](#merge-release-branch-into-main) - [Publish the Dataverse Client Javascript package](#publish-the-dataverse-client-javascript-package) - [Create a Draft Release on GitHub and Tag the Version](#create-a-draft-release-on-github-and-tag-the-version) @@ -42,6 +43,52 @@ This command will update the version in the `package.json` and `package-lock.jso If everything looks good, you can push the changes to the repository. +## Update the changelog + +**Note**: Contributors should have already added their changes to the `[Unreleased]` section as part of their pull requests (see [CONTRIBUTING.md](../.github/CONTRIBUTING.md#changelog-guidelines) for details). + +Before releasing, ensure the changelog is properly prepared: + +1. **Review the [Unreleased] section** in `CHANGELOG.md` and `packages/design-system/CHANGELOG.md` +2. **Move entries from [Unreleased] to the new version section**: + + ```markdown + ## [vX.X.X] -- YYYY-MM-DD + + ### Added + + - Feature descriptions from unreleased section + + ### Changed + + - Changes from unreleased section + + ### Fixed + + - Bug fixes from unreleased section + + ### Removed + + - Removals from unreleased section + ``` + +3. **Clear the [Unreleased] section** but keep the structure: + + ```markdown + ## [Unreleased] + + ### Added + + ### Changed + + ### Fixed + + ### Removed + ``` + +4. **Update the version links** at the bottom of the changelog files +5. **Commit the changelog updates** as part of the release preparation + ## Merge "release branch" into "main" Create a pull request to merge the `release` branch into the `main` branch. @@ -96,7 +143,7 @@ Go to https://github.com/IQSS/dataverse-client-javascript/releases/new to start - Under "Release title" use the same name as the tag such as v3.5.0. -- Add a description of the changes included in this release. You should include a link to the recently published npm version and summarize the key updates, fixes, or features. +- Add a description of the changes included in this release. You should include a link to the recently published npm version and summarize the key updates, fixes, or features. You can copy the content from the corresponding version section in `CHANGELOG.md` for consistency. - Click "Save draft" because we do not want to publish the release yet.