Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
203 lines (138 loc) · 4.17 KB

CONTRIBUTING.md

File metadata and controls

203 lines (138 loc) · 4.17 KB

How to contribute to Fory

Finding good first issues

See Good First Issues.

How to create an issue

Create an issue with this form.

How to title your PR

Generally we follows the Conventional Commits for pull request titles, since we will squash and merge the PR and use the PR title as the first line of commit message.

For example, here are good PR titles:

  • feat(java): support xxx feature
  • fix(c++): blablabla
  • chore(python): remove useless yyy file

If the submitted PR affects the performance of Fory, we strongly recommend using the perf type, and need to provide benchmark data in the PR description. For how to run the benchmark, please check Fory Java Benchmark.

For more details, please check pr-lint.yml.

Testing

For environmental requirements, please check DEVELOPMENT.md.

Python

cd python
pytest -v -s .

Java

cd java
mvn -T10 clean test

C++

bazel test $(bazel query //...)

GoLang

cd go/fory
go test -v
go test -v fory_xlang_test.go

Rust

cd rust
cargo test

JavaScript

cd javascript
npm run test

Code Style

Run all checks: bash ci/format.sh --all.

License headers

docker run --rm -v $(pwd):/github/workspace ghcr.io/korandoru/hawkeye-native:v3 format

Java

cd java
# code format
mvn spotless:apply
# code format check
mvn spotless:check
mvn checkstyle:check

Python

cd python
# install dependencies fro styling
pip install black==22.1.0 flake8==3.9.1 flake8-quotes flake8-bugbear click==8.0.2
# format python code
black pyfory

C++

git ls-files -- '*.cc' '*.h' | xargs -P 5 clang-format -i

GoLang

cd go/fory
gofmt -s -w .

Rust

cd rust
cargo fmt

JavaScript

cd javascript
npm run lint

Debug

Java

Fory supports dump jit generated code into local file for better debug by configuring environment variables:

  • FORY_CODE_DIR：The directory for fory to dump generated code. Set to empty by default to skip dump code.
  • ENABLE_FORY_GENERATED_CLASS_UNIQUE_ID: Append an unique id for dynamically generated files by default to avoid serializer collision for different classes with same name. Set this to false to keep serializer name same for multiple execution or AOT codegen.

By using those environment variables, we can generate code to source directory and debug the generated code in next run.

Python

cd python
python setup.py develop
FORY_DEBUG=true python setup.py build_ext --inplace
# For linux
cygdb build

C++

See the Debugging C++ doc.

Debug Crash

Enable core dump on Macos Monterey 12.1:

/usr/libexec/PlistBuddy -c "Add :com.apple.security.get-task-allow bool true" tmp.entitlements
codesign -s - -f --entitlements tmp.entitlements /Users/chaokunyang/anaconda3/envs/py3.8/bin/python
ulimit -c unlimited

then run the code:

python fory_serializer.py
ls -al /cores

Profiling

C++

# Dtrace
sudo dtrace -x ustackframes=100 -n 'profile-99 /pid == 73485 && arg1/ { @[ustack()] = count(); } tick-60s { exit(0); }' -o out.stack
sudo stackcollapse.pl out.stack > out.folded
sudo flamegraph.pl out.folded > out.svg

Extracts compile_commands.json

bazel run :refresh_compile_commands

Website

Fory's website consists of static pages hosted at https://github.com/apache/fory-site.

All updates about docs under guide and benchmarks will be synced to the site repo automatically.

If you want write a blog, or update other contents about the website, please submit PR to the site repo.