Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
137 lines (93 loc) · 7.6 KB

CONTRIBUTING.md

File metadata and controls

137 lines (93 loc) · 7.6 KB
Raw

Contributing

We are glad that you are willing to contribute to the OpenTiny NEXT-SDKs project. There are many forms of contribution, and you can choose one or more of them according to your strengths and interests:

  • Report new defect
  • Provide more detailed information for existing defects, such as supplementary screenshots, reproduction steps, or minimal reproducible demo links
  • Submit Pull requests to fix typos in the document or make the document clearer and better
  • Add the official assistant WeChat opentiny-official and join the technical exchange group to participate in the discussion

When you use NEXT-SDKs and participate in many of the above contributions, as you become familiar with the project, you can try to do something more challenging, such as:

  • Fix defects, you can start with Good-first issue
  • Implement new features
  • Improve unit testing
  • Translate the document
  • Participate in code review

Bug Reports

If you encounter problems while using OpenTiny NEXT-SDKs, you are welcome to submit an Issue. Before submitting, please read the relevant official documentation carefully to confirm whether this is a defect or an unimplemented function.

If it is a defect, select the Bug report template when creating a new Issue. The title follows the format [packageName] defect description. For example: [next-sdk] registerPageAgentTool config not replaced on re-register.

Issue that reports defects mainly needs to fill in the following information:

  • Version numbers of @opentiny/next-sdk, @opentiny/next-remoter (if involved), and Node.js
  • The performance of the defect can be illustrated by screenshot; if there is an error, post the error message
  • Defect reproduction steps, preferably with a minimum reproducible demo link

If it is a new feature, select the Feature request template. The title follows the format [packageName] new feature description. For example: [next-remoter] support custom theme variables.

The following information is required for the Issue of the new feature:

  • What problems does this feature mainly solve for users?
  • What is the API of this feature?

Pull Requests

Before submitting a pull request, please make sure that your submission is in line with the overall plan of NEXT-SDKs. Generally, issues marked as bug are encouraged for pull requests. If you are not sure, you can create a Discussion for discussion.

Pull Request Specification

Commit Message

The commit message should be in the form of type(scope): description, e.g. fix(next-sdk): fix page-agent-tool a11y tree incremental diff.

  1. type: must be one of build, chore, ci, docs, feat, fix, perf, refactor, revert, release, style, test, improvement.

  2. scope (optional): package or module name under packages/, e.g.:

    • Package names: next-sdk, next-remoter, next-wxt, doc-ai, vue-playground, next-sdk-playground, next-docs
    • Module under next-sdk: next-sdk/transport, next-sdk/agent, etc.

Pull Request Title

  1. The title follows the same convention as the commit message: type(scope): description.

  2. Example titles:

    • Added next-sdk documentation: docs(next-docs): add MCP transport guide
    • Fixed page-agent bug: fix(next-sdk): fix setPageAgentToolConfig merge behavior
    • New feature for next-remoter: feat(next-remoter): support custom theme

Pull Request Description

The PR description uses a template. Please fill in the relevant information according to the template, mainly including:

  • Summary / behavior change / breaking change
  • Use a conventional title (fix / feat / docs / …); the gate infers type from the title (labels as fallback)
  • Bugfix: the PR diff must include a test under packages/*/test/**/*.{test,spec}.* whose content contains 复现：
  • Feature: the PR diff must include both a complete Spec directory packages/<pkg>/specs/REQ-*/ and at least one changed test under packages/*/test/**/*.{test,spec}.*; skip-spec only exempts trivial changes from the Spec requirement, not the test requirement
  • Link Issues via GitHub when applicable

Local Startup Steps

  • Click the Fork button in the upper right corner of the next-sdk repository to fork the upstream repository to your personal repository.
  • Clone your personal repository to local.
  • Associate with the upstream repository to sync the latest code.
  • Run pnpm install in the project root to install dependencies.
  • Run pnpm dev to start the doc-ai example, or pnpm wiki to start the VitePress documentation site.
# Replace username with your GitHub username
git clone git@github.com:username/next-sdk.git
cd next-sdk

# Associate upstream repository
git remote add upstream git@github.com:opentiny/next-sdk.git

# Install dependencies (use pnpm, not npm or yarn)
pnpm install

# Start doc-ai example
pnpm dev

# Start VitePress documentation
pnpm wiki

# Other development commands
# pnpm dev:remoter    - next-remoter component dev server
# pnpm dev:wxt        - browser extension
# pnpm dev:vue-playground  - Vue playground
# pnpm dev:playground - Next.js playground

Submit a PR

  • Make sure you have completed the local startup steps and can run the project normally.
  • Sync the latest code from the upstream dev branch: git pull upstream dev.
  • Create a new branch from upstream dev: git checkout -b username/feature1 upstream/dev. Branch name suggestion: username/feat-xxx / username/fix-xxx.
  • Code locally.
  • Submit according to the Conventional Commits specification. PRs that do not follow the specification may not be merged.
  • Push to your remote: git push origin branchName.
  • Open the Pull requests page of the next-sdk repository and click New pull request to submit the PR.
  • Fill in the PR template: checklist, PR type, related Issue ID, whether it is a breaking change.
  • Project maintainers will conduct Code Review and leave comments.
  • Adjust the code according to the feedback. Note: after a branch has opened a PR, subsequent commits will be synced automatically; you do not need to resubmit the PR.
  • Project maintainer merges the PR.

Thank you for your contribution!

Join OpenTiny Community

If you are interested in our open-source project, you are welcome to join the community in the following ways:

  • Add official assistant WeChat: opentiny-official to join the technical exchange group.
  • Join the mailing list: opentiny@googlegroups.com

If you have submitted an Issue or PR to OpenTiny, you can comment on the Issue or Pull Request and ask @all-contributors to add you as a contributor:

@all-contributors please add @<username> for <contributions>

For detailed rules, see allcontributors.org - bot usage.

Contributors

We sincerely thank all contributors who have participated in the OpenTiny NEXT-SDKs project! Your contributions are reflected in the contributors section of the repository. We welcome every form of contribution, including code, documentation, and feedback.