Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
238 lines (179 loc) · 7.63 KB

CONTRIBUTING.md

File metadata and controls

238 lines (179 loc) · 7.63 KB

Contributing

Contributing with Issues

Before opening an issue try to search the existing ones for the same problem.

Make sure to include on your issue the following information:

  • Node.js Version
  • package manager version
  • Operational System (name and version)
  • Package version
  • Logs of the installation

Contributing with Code

The package manager used on this project is pnpm

The addon lib code is written in Typescript, while the addon itself is written in C++.

Folders ./scripts and ./tools contain scripts in Javascript, those are used mostly during installation and on CI.

C/C++

Code Style

C/C++ code is written following Google style guide (with some minor changes), and clang-format can/should be used to automatically format the code. There is already a .clang-format on the repository.

Linting

cpplint is used to lint C/C++ code

Typescript / Javascript

Code Style

TS/JS code should be formatted using prettier

Linting

ts-lint is used to lint TS code, while JS code is using eslint.

Setup

If on Windows, first you will need to grab the deps:

$ node scripts/update-deps.js

Install the dependencies, this will also build the addon:

$ pnpm install

If you made some change to the C++ code, you can just build the addon again:

$ pnpm pregyp build

In case you need to rebuild:

$ pnpm pregyp rebuild

If on unix and using the build.sh scripts, you also need to provide the path to the curl config file:

npm_config_macos_universal_build=true \
npm_config_curl_config_bin=~/deps/libcurl/build/x.y.z/bin/curl-config \
pnpm pregyp build --debug

If you have any issues with the build process, please refer to a readme build troubleshooting section.

Adding New libcurl Options

If you want to include a new libcurl option on the addon, those are the basic steps:

  1. Add the option to their correct category on Curl.cc There are different vectors there for the expected type of the option's value, like curlOptionInteger, curlOptionString, etc. Make sure to use a #if directive to include this option only if building against a libcurl version that supports it, otherwise there will be an compilation error on older versions.
  2. In case the option expects a value of type other than number | string | boolean, you must also add it to their respective key on the object optionKindMap inside ./scripts/data/options.js. In case you add it to the other key, which means this option has a specific value, you must also add the option expected value type to the object optionKindValueMap right below, on that same file.
  3. If the option may use an enum, you should also create or update the existing enum. For example, libcurl 7.75.0 added AWS Sig v4 authentication method, for that a new option and constant were added in libcurl, CURLOPT_AWS_SIGV4 and CURLAUTH_AWS_SIGV4. To add support for that option we:
  4. Run node ./scripts/build-constants.js, this will generate an updated list of options on ./lib/generated/, and also update the files [./lib/Curl.ts] and [./lib/Easy.ts] with overloads for the setOpt method. Make sure the options added are correct.
  5. If running the above adds extra options that you do not want to add / are not related to the options you are adding, please feel free to remove them manually from the generated output. We will try to improve this experience later, but for now you have to manually remove them.

Changing libcurl Version Used on Prebuilt Binaries for Windows

We use vcpkg for this. Simply change the version on the file vcpkg.template.json

Building Electron

Sample command you could use from the root of this repository:

LIBCURL_RELEASE=8.17.0 PUBLISH_BINARY="false" ./scripts/ci/build.sh

npm_config_curl_config_bin=~/deps/libcurl/build/8.17.0/bin/curl-config \
 npm_config_curl_static_build=true \
 npm_config_runtime=electron \
 npm_config_target=21.2.0 \
 npm_config_disturl=https://www.electronjs.org/headers \
 pnpm pregyp rebuild --debug

You can also use electron-rebuild, e.g for macOS:

npm_config_curl_static_build=true \
npm_config_macos_universal_build=true \
npm_config_curl_config_bin=~/deps/libcurl/build/8.17.0/bin/curl-config \
pnpm exec electron-rebuild

Debugging with lldb

  1. Install lldb On Debian based linux:
sudo apt-get install lldb
  1. Install Node.js lldb plugin:
pnpm i -g llnode

or:

brew install llnode
# then follow instructions
  1. Run script that causes core dump
llnode -- /path/to/bin/node --abort_on_uncaught_exception script.js
  1. Profit

More information go to https://github.com/nodejs/llnode

Publishing New Releases

For publishing there is a GitHub action workflow to publish new releases at: https://github.com/JCMais/node-libcurl/actions/workflows/publish.yml

Manual Publishing

We are using np for releases.

Semver Major / Minor / Patch

  1. Checkout master
  2. Merge changes from develop
  3. Create version
  4. Publish

So basically:

git checkout master
git merge develop

And then:

npx np [major|minor|patch]

or if you are having trouble with np:

pnpm publish

or even if you are having trouble with pnpm:

npm version [major|minor|patch]
npm publish

And finally

git push --follow-tags
git checkout develop
git merge master
git push

Prereleases

For prereleases, use something like this from the develop branch:

$ pnpm exec np prerelease --any-branch --tag next

If for some reason np fails to run, you can use this command to skip cleaning up and use npm to publish:

$ pnpm exec np prerelease --no-cleanup --any-branch --tag next

Build Matrix

We are using three CI providers:

  • CircleCI
  • GitHub Actions
  • AppVeyor

Each CI provider is responsible for some builds:

CircleCI:

  • Node.js (Alpine)
  • Electron (linux)
  • NW.js (linux)

GitHub Actions:

  • Node.js (Linux, macOS)
  • Electron (macOS)
  • NW.js (macOS)

AppVeyor:

  • Node.js (Win64, Win32)
  • Electron (Win64, Win32)

GitHub Actions are also used to lint PRs, for that a build runs on Linux.