Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
125 lines (77 loc) · 5.92 KB

CONTRIBUTING.md

File metadata and controls

125 lines (77 loc) · 5.92 KB
Raw

Contributing

All contributions are welcome to this project.

Contributor License Agreement

Before a contribution can be merged into this project, please fill out the Contributor License Agreement (CLA) located at:

http://opensource.box.com/cla

To learn more about CLAs and why they are important to open source projects, please see the Wikipedia entry.

Code of Conduct

This project adheres to the Box Open Code of Conduct. By participating, you are expected to uphold this code.

How to contribute

  • File an issue — If you found a bug, want to request an enhancement, or plan to implement something (bug fix or feature), start with an issue on npm-box issues.
  • Send a pull request — If you want to contribute code, please open an issue first so we can align on the approach.

What this repository is

This repo publishes the box npm meta-package: thin re-exports of box-node-sdk and @box/cli, plus packaging (package.json exports, scripts/postbuild.cjs, scripts/postinstall.js, docs such as README.md and llms.txt). Changes to SDK or CLI behavior usually belong in those upstream repositories; here we focus on the umbrella package surface, build, and developer experience.

Local development

  1. Clone this repository.
  2. Install dependencies: npm install.
  3. Build artifacts: npm run build (runs ESM/CJS/type emit and postbuild).
  4. Verify types: npm run typecheck.
  5. Lint: npm run lint.
  6. Run npm test when you add or change tests. (The repo may not yet include a Jest suite; if you introduce tests, place them where Jest’s defaults will discover them, or document the layout in your PR.)

Make changes in src/ (TypeScript sources). The compiled output lives under dist/ and is generated by the build; do not hand-edit dist/ in pull requests.

After editing README.md, if you use doctoc for the table of contents, refresh it with npx doctoc README.md before submitting.

Pull request best practices

We want to accept your pull requests. Please follow these steps.

Step 1: File an issue

Before writing any code, please file an issue stating the problem you want to solve or the feature you want to implement. That gives us a chance to provide feedback before you invest significant time. There may be known limitations, or a fix may already be in progress.

Step 2: Fork this repository on GitHub

This creates your own copy of the repository.

Step 3: Add the upstream remote

The upstream repository is the Box organization project. For example:

git remote add upstream git@github.com:box/npm-box.git

Use https://github.com/box/npm-box.git instead if you prefer HTTPS.

Step 4: Create a feature branch

Use a descriptive branch name, for example fix-export-map or docs-readme-clarify.

Step 5: Push your feature branch to your fork

We use semantic versioning and encourage the Conventional Commits format. Keep one feature branch per issue.

Scopes: For changes that affect this meta-package’s public surface (exports, re-exports, semver-relevant packaging), prefer the box scope. For documentation-only or internal tooling changes, the scope is optional.

tag(scope): short description
tag: short description (when scope is not applicable)

Longer description here if necessary.

Examples with scope:

  • feat(box): add new subpath export for …
  • fix(box): correct types path in export map
  • feat(box)!: remove deprecated export

Examples without scope:

  • docs: update README
  • chore: bump devDependency
  • ci: adjust workflow

The summary line should stay around 72 characters or fewer. For breaking changes, include ! after the type (or after the scope), for example feat(box)!: drop legacy export. See conventional commit types for common type values.

Commit types (semver intuition)

  • Breaking — Removes or incompatible changes to public API or supported import paths: treat as a major bump (! in the message helps reviewers spot this).
  • feat — New backwards-compatible capability: minor.
  • fix — Bug fix: patch.
  • docs, chore, ci, etc. — No intended runtime or export change; typically no version impact unless they accompany releasable code.
Commit message Release type New version
feat(boxsdk)!: remove old files endpoints Major ("breaking") X+1.0.0
feat(boxsdk): add new file upload endpoint Minor ("feature") X.Y+1.0
fix(boxsdk): file streaming during download Patch ("fix") X.Y.Z+1
docs: update README No release X.Y.Z
chore: update build configuration No release X.Y.Z
refactor(boxsdk): rename a variable (invisible change) No release X.Y.Z

Step 6: Rebase

Before opening a pull request, rebase onto upstream default branch (usually main):

git fetch upstream
git rebase upstream/main

Step 7: Run checks

Ensure npm run build, npm run typecheck, and npm run lint succeed. Run npm test when your change includes or affects automated tests.

Step 8: Open the pull request

Open a pull request from your feature branch to box/npm-box. Describe what changed and link the related issue.

We prefer one issue per pull request when practical, to keep history reviewable and bisect-friendly.