You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@fury.apache.org by ti...@apache.org on 2023/12/26 10:46:33 UTC
(incubator-fury) branch CONTRIBUTING created (now 8191fc1d)
This is an automated email from the ASF dual-hosted git repository.
tison pushed a change to branch CONTRIBUTING
in repository https://gitbox.apache.org/repos/asf/incubator-fury.git
at 8191fc1d docs: polish CONTRIBUTING doc
This branch includes the following new commits:
new 8191fc1d docs: polish CONTRIBUTING doc
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fury.apache.org
For additional commands, e-mail: commits-help@fury.apache.org
(incubator-fury) 01/01: docs: polish CONTRIBUTING doc
Posted by ti...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
tison pushed a commit to branch CONTRIBUTING
in repository https://gitbox.apache.org/repos/asf/incubator-fury.git
commit 8191fc1dc3ba6830b91560572c0eca44cadff5a9
Author: tison <wa...@gmail.com>
AuthorDate: Tue Dec 26 18:46:23 2023 +0800
docs: polish CONTRIBUTING doc
Signed-off-by: tison <wa...@gmail.com>
---
.github/pull_request_template.md | 19 -----------
CONTRIBUTING.md | 73 +++++++++++++++++++++++-----------------
docs/cpp_debug.md | 7 ++--
3 files changed, 47 insertions(+), 52 deletions(-)
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
deleted file mode 100644
index fdd2cadf..00000000
--- a/.github/pull_request_template.md
+++ /dev/null
@@ -1,19 +0,0 @@
-<!--
-Thank you for your contribution!
-
-Please review https://github.com/apache/incubator-fury/blob/main/CONTRIBUTING.rst before opening a pull request.
--->
-
-## What do these changes do?
-
-<!-- Please give a short brief about these changes. -->
-
-## Related issue number
-
-<!-- Are there any issues opened that will be resolved by merging this change? -->
-Closes #xxxx
-
-## Check code requirements
-
-- [ ] tests added / passed (if needed)
-- [ ] Ensure all linting tests pass, see [here](https://github.com/apache/incubator-fury/blob/main/CONTRIBUTING.rst) for how to run them
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e03edf0f..332e7dae 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,45 +1,53 @@
# How to contribute to Fury
-## Finding good first issues 🔎
-See [Good First Issue](https://github.com/apache/incubator-fury/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) for open good first issues.
+
+## 🔎 Finding good first issues
+
+See [Good First Issues](https://github.com/apache/incubator-fury/contribute).
## How to create an issue
-See https://github.com/apache/incubator-fury/issues for open issues.
-## Testing 🧪
+Create an issue with [this form](https://github.com/apache/incubator-fury/issues/new/choose).
+
+## 🧪 Testing
+
### Python
+
```bash
cd python
pytest -v -s .
```
+
### Java
+
```bash
cd java
mvn -T10 clean test
```
### C++
+
```bash
bazel test $(bazel query //...)
```
### GoLang
+
```bash
cd go/fury
-# run tests
go test -v
-# run xlang tests
go test -v fury_xlang_test.go
```
### Rust
+
```bash
cd rust
cargo test
```
-## Styling 😎
+## 😎 Code Style
-Run all checks: `bash ci/format.sh --all`
+Run all checks: `bash ci/format.sh --all`.
### License headers
@@ -57,6 +65,7 @@ mvn spotless:apply
mvn spotless:check
mvn checkstyle:check
```
+
### Python
```bash
@@ -88,47 +97,57 @@ cargo fmt
```
## Debug
-### Java Debug
-#### JIT DEBUG
+
+### Java
+
Fury supports dump jit generated code into local file for better debug by configuring environment variables:
+
- `FURY_CODE_DIR`:The directory for fury to dump generated code. Set to empty by default to skip dump code.
- `ENABLE_FURY_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 Debug
+### Python
+
```bash
cd python
python setup.py develop
```
-* cython: use `cython --cplus -a pyfury/_serialization.pyx` to produce an annotated
- html file of the source code. Then we can analyze interaction between
- Python objects and Python’s C-API.
-* Debug
- https://cython.readthedocs.io/en/latest/src/userguide/debugging.html
+* Use `cython --cplus -a pyfury/_serialization.pyx` to produce an annotated HTML file of the source code. Then you can analyze interaction between Python objects and Python's C API.
+* Read more: https://cython.readthedocs.io/en/latest/src/userguide/debugging.html
+
```bash
FURY_DEBUG=true python setup.py build_ext --inplace
# For linux
cygdb build
```
-### C++ debug
-See [cpp_debug](https://github.com/apache/incubator-fury/blob/main/docs/cpp_debug.md) doc.
+### C++
+
+See the [Debugging C++](docs/cpp_debug.md) doc.
### Debug Crash
-Enable core dump on Macos Monterey 12.1
+
+Enable core dump on Macos Monterey 12.1:
+
```bash
- /usr/libexec/PlistBuddy -c "Add :com.apple.security.get-task-allow bool true" tmp.entitlements
+/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:
+
+```bash
python fury_serializer.py
ls -al /cores
```
## Profiling
+
### C++
+
```bash
# Dtrace
sudo dtrace -x ustackframes=100 -n 'profile-99 /pid == 73485 && arg1/ { @[ustack()] = count(); } tick-60s { exit(0); }' -o out.stack
@@ -136,16 +155,10 @@ sudo stackcollapse.pl out.stack > out.folded
sudo flamegraph.pl out.folded > out.svg
```
-## CI
-### Login into ci machine
-```yaml
- - name: Setup tmate session
- uses: mxschmitt/action-tmate@v3
-```
-
## Website
-Fury website are static pages hosted by github pages under https://github.com/fury-project/fury-sites.
-All updates about docs under [guide](./docs/guide) and [benchmarks](./docs/benchmarks) will be synced to [fury-sites](https://github.com/fury-project/fury-sites) automatically.
+Fury's website consists of static pages hosted at https://github.com/apache/incubator-fury-site.
+
+All updates about docs under [guide](docs/guide) and [benchmarks](docs/benchmarks) will be synced to the site repo automatically.
-If you want write a blog, or update other contents about fury website, please submit PR to [fury-sites](https://github.com/fury-project/fury-sites).
+If you want write a blog, or update other contents about the website, please submit PR to the site repo.
diff --git a/docs/cpp_debug.md b/docs/cpp_debug.md
index 18c4e6ed..284eff40 100644
--- a/docs/cpp_debug.md
+++ b/docs/cpp_debug.md
@@ -1,4 +1,5 @@
-# C++ Debugging
+# Debugging C++
+
Debug C++ is tricky and binary protocol bug is hard to locate without debugging support, but setup
debugging support for bazel project is not easy.
@@ -11,12 +12,12 @@ java/python debugging.
<img src="images/vscode_debug_fury.jpg" alt="Fury Debugging Example" width="50%" height="50%" />
## Notes
+
- For Macos: Install `CodeLLDB` vscode plugin
- For Linux:
- install gdb for fedora/centos by `sudo yum install -y gdb`
- install gdb for fedora/centos by `sudo apt-get install gdb`
- If debugging doesn't work, please select correct debug/run options:
-<img src="images/vscode_select_debug_run.png" alt="select correct debug/run options" width="50%" height="50%" />
+ <img src="images/vscode_select_debug_run.png" alt="select correct debug/run options" width="50%" height="50%" />
- Debug will jump to source files in bazel generated directory, we need to return raw files in source tree
for debugging again: <img src="images/jmp_generate_file.png" alt="jump to generated files" width="50%" height="50%" />
-
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fury.apache.org
For additional commands, e-mail: commits-help@fury.apache.org