← Back to Help

Table of Contents

Pull Requests

Pull requests let you propose changes from one bookmark to another and request code review before merging. They provide a structured workflow for discussing changes, iterating on feedback, and maintaining a clean project history.

Bookmark Workflow

Isurus uses Mercurial bookmarks as the basis for pull requests. Bookmarks are lightweight, movable references — similar to Git branches — that track the tip of a line of development.

1. Create a Bookmark

Start from the latest revision on the target branch (usually default) and create a new bookmark:

hg update default
hg pull -u
hg bookmark my-feature

2. Make Commits

Work normally and commit your changes. The bookmark advances with each commit:

# Edit files...
hg commit -m "Add input validation to signup form"

# Continue working...
hg commit -m "Add unit tests for validation"

3. Push the Bookmark

Push the bookmark to Isurus. The -B flag publishes the bookmark itself, not just the changesets:

hg push -B my-feature

4. Create a Pull Request on Isurus

Once the bookmark is pushed, open a pull request through the web UI (see below).

Full Example

# Clone and update to default
hg clone ssh://isurus-host/myorg/myrepo
cd myrepo
hg update default

# Create a feature bookmark
hg bookmark add-search-api

# Work and commit
hg commit -m "Add search endpoint to API"
hg commit -m "Add search tests and documentation"

# Push the bookmark
hg push -B add-search-api

# Now open a pull request on the Isurus web UI

Creating a Pull Request

  1. Navigate to your repository.
  2. Click the Pull Requests tab.
  3. Click New Pull Request.
  4. Fill in the form:
    • Source bookmark — Select the bookmark containing your changes (e.g., add-search-api).
    • Target branch — Select the branch to merge into (usually default).
    • Title — A short summary of the changes.
    • Description — Detailed explanation of what changed and why. Supports Markdown formatting.
  5. Click Create Pull Request.

Note: You must be an organization member to create pull requests. Only one open pull request can exist per source bookmark at a time.

Issue References

You can link pull requests to issues by referencing issue numbers in the PR description or comments.

Linking to Issues

Type #N anywhere in the description or a comment to create a link to issue N:

This PR adds the search feature described in #12.
See also #15 for the related UI work.

Auto-Closing Issues on Merge

Use a close keyword followed by #N to automatically close the referenced issue when the pull request is merged (not when the PR is created):

Keyword Example
close, closes, closed closes #8
fix, fixes, fixed fixes #42
resolve, resolves, resolved resolves #15

Keywords are case-insensitive. You can reference multiple issues:

This PR fixes #8 and resolves #15.

When the PR is merged, issues #8 and #15 will be automatically closed, and their timelines will show "closed via PR #Y".

Important: Auto-close only happens on merge. Closing or reopening a PR without merging does not affect referenced issues.

Code Review

Viewing the Diff

When you open a pull request, Isurus displays:

  • The list of changesets (commits) included in the PR.
  • A unified diff showing all changes between the source bookmark and the target branch.

Leaving Comments

Organization members can leave comments on the pull request to provide feedback, ask questions, or approve the changes. Comments support Markdown formatting and issue references (#N).

Updating a Pull Request

To address review feedback, simply push additional commits to the same bookmark:

# Make changes based on review feedback
hg commit -m "Address review: improve error handling"

# Push the updated bookmark
hg push -B my-feature

The pull request updates automatically — the diff and changeset list reflect the latest state of the bookmark. There is no need to close and reopen the PR.

Merging

When the changes are approved and ready:

  1. Open the pull request.
  2. Click the Merge button.

Merging is available to the repository owner or the PR author. When the merge completes:

  • The source bookmark's changesets are merged into the target branch.
  • Issues referenced with close keywords (closes, fixes, resolves and their variants) are automatically closed.
  • Closed issues show "closed via PR #Y" on their timeline.
  • The pull request status changes to Merged.

Closing and Reopening

Closing Without Merging

If a pull request is no longer needed, any organization member can close it without merging:

  1. Open the pull request.
  2. Click the Close button.

Closing a PR does not merge any changes and does not affect referenced issues.

Reopening a Closed Pull Request

A closed (not merged) pull request can be reopened:

  1. Open the closed pull request.
  2. Click the Reopen button.

Note: Merged pull requests cannot be reopened.

Pagination and Filtering

The pull request list supports filtering and pagination:

Control Options
Status filter Open, Merged, Closed
Page size 20, 50, or 100 per page
Navigation Previous / Next page links

The list header shows the count of open pull requests. Select a status tab to switch between open, merged, and closed pull requests.