Skip to main content
Version: Current (3.x)

Data Viz Wordpress Release Guide

Repository: https://github.com/devgateway/data-viz-wordpress

  • Data Viz Wordpress contains several libraries that are used to build custom Wordpress blocks and also utilities to develop wordpress.
  • It is also used to build the Data Viz Wordpress image.
  • The release process uses a tool called changeset to manage the release process. Changesets is a tool that helps to manage the release process by creating a changelog and a version number in monorepos.

Packages in the repository​

Release Process​

  • The release process is triggered by a push to the main branch.
  • To create a release, one needs to create a changeset file by running the following command:
npx changeset add
  • This will open a prompt to select the packages that are being released and the summary of the changes.
  • Once the changes are entered, the changeset .md file is created. This file is editable and can be edited to add more details to the release.
  • Once pushed, one opens a pull request to the main branch and waits for it to be merged.
  • Changesets Github action checks if there is a changeset file and if there is, it opens a pull request with the updated version number and changelog for the affected packages.
  • Once the pull request is merged, the changesets Github action will create a release and push it to the NPM registry.

Visual Representation​

Best Practices​

Writing Good Changesets​

Good Examples​

---
"@devgateway/dvz-ui-react": minor
---

Add horizontal bar chart component

- New HorizontalBarChart component with full customization
- Supports all existing bar chart features in horizontal orientation
- Includes TypeScript definitions and documentation
- Fixes accessibility issues with chart legends
---
"@devgateway/wp-react-lib": patch
---

Fix WordPress API authentication headers

Resolves issue where authentication tokens were not properly passed to WordPress REST API calls, causing 401 errors in production environments.

Avoid​

---
"@devgateway/dvz-ui-react": minor
---

Updates

Changeset Guidelines​

  1. Be descriptive: Explain what changed and why
  2. Include context: Help users understand the impact
  3. Reference issues: Link to GitHub issues when relevant
  4. Use proper grammar: Changesets become part of the changelog
  5. Group related changes: One changeset per logical change

Versioning Strategy​

  • Patch: Bug fixes, documentation, internal refactoring
  • Minor: New features, new components, enhanced functionality
  • Major: Breaking API changes, removed features, major restructuring

Troubleshooting​

Common Issues​

Changeset Not Generated​

# Make sure you're in the root directory
cd /path/to/data-viz-ui

# Check changeset status
npx changeset status

# Add changeset manually
npx changeset add

Version Conflicts​

# Reset to clean state
git checkout main
git pull origin main

# Re-run versioning
pnpm version

Publishing Failures​

# Check npm authentication
npm whoami

# Verify package builds
pnpm build

# Check for existing versions
npm view @devgateway/dvz-ui-react versions --json

Pre-release Issues​

# Check pre-release mode
npx changeset pre --help

# Exit pre-release mode if stuck
npx changeset pre exit

Debugging Commands​

# Check current changeset status
npx changeset status

# Preview what versions would be bumped
npx changeset version --dry-run

# See changeset configuration
cat .changeset/config.json

# Check package dependency graph
npx changeset status --verbose

Integration with Development Workflow​

During Development​

  1. Create feature branch
  2. Develop feature
  3. Add changeset before committing
  4. Include changeset in commit
  5. Create pull request

Code Review​

Reviewers should check:

  • Changeset matches the scope of changes
  • Version bump type is appropriate
  • Description is clear and helpful
  • Internal dependencies are considered

Release Process​

  1. Merge approved PRs with changesets
  2. Run version command (creates version PR)
  3. Review and merge version PR
  4. Publish packages (manual or automated)
  5. Verify publication on npm and GitHub

Resources​