This is an automated email from the ASF dual-hosted git repository.
tison pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-fury.git
The following commit(s) were added to refs/heads/main by this push:
new e0cd19aa docs: polish CONTRIBUTING doc (#1257)
e0cd19aa is described below
commit e0cd19aab34a08699fd29034dc4fc43392f60592
Author: tison <[email protected]>
AuthorDate: Tue Dec 26 18:48:42 2023 +0800
docs: polish CONTRIBUTING doc (#1257)
Signed-off-by: tison <[email protected]>
---
.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: [email protected]
For additional commands, e-mail: [email protected]
