Please add the contributing guide

[julianharty]

Context

In Line 23 CONTRIBUTING.md is referenced but doesn't seem to exist. How about adding one and referencing it in various places including the project's README in the Contribution section?

Let me know if you'd like to to help create this. I've added some thoughts here to start the conversation - you know the project and the codebase far better than I do and I expect you've ideas and plans to improve it that I'm not currently aware of.

Rustfmt

Presumably it'd include running rustfmt as illustrated in the CI workflow:

rustfmt --edition 2024 $(git ls-files '*.rs')

BTW this command hangs silently if there are no files in the commit that match *.rs which may happen occasionally e.g. if a commit only has markdown files. Something like:

files=$(git ls-files '*.rs')
if [ -z "$files" ]; then
  echo "No Rust files found"
  exit 2
fi

rustfmt --check --edition 2024 $files
exit $?

or

files=$(git ls-files '*.rs'); if [ -z "$files" ]; then exit 2; else rustfmt --check --edition 2024 $files; fi

may be more robust? (I've asked it to return 2 to make this condition explicit here, however you might prefer it to return 0 and write a log message such as:

files=$(git ls-files '*.rs'); [ -z "$files" ] && { echo "No Rust files found, skipping rustfmt"; exit 0; } || rustfmt --check --edition 2024 $files

More tests please?

Code contributions might benefit from additional automated tests. If so, what sort of guidance would help contributors? I'd suggest a good start is helping them know how to run the current automated unit tests and the cargo fuzz tests.

cargo test --all-features -p holo-bfd -p holo-bgp -p holo-isis -p holo-ldp -p holo-ospf -p holo-rip -p holo-vrrp

and

fuzz/fuzz-all.sh

What makes tests valuable and maintainable? Where would you like them adding in the codebase e.g. on a per routing protocol basis?

Testing holo as a system?

Perhaps this is outside the scope of this request, nonetheless if contributors are able to run holo and test it as a system that may help increase the confidence their contributions don't break holo (and might even improve its behaviour :) )

Out of date guides?

I found https://github.com/holo-routing/holo/wiki/Holo-Guide-%E2%80%90-Setting-up-dependencies partly as I was trying to work out why the fuzz test targets don't compile on one of my ubuntu machines where I'm building holo for the first time. (The compilation error is rust-lld: error: unable to find library -lyang but the details are out-of-scope for this ticket). Anyway, is that guide still accurate? e.g. it includes cloning libyang then building and installing it locally.

[rwestphal]

@julianharty Thanks for bringing this up. I intend to add a CONTRIBUTING.md file as part of a broader effort to improve the developer documentation and make Holo more accessible to contributors. I'll keep this issue open until that's done.

Presumably it'd include running rustfmt as illustrated in the CI workflow:

rustfmt --edition 2024 $(git ls-files '*.rs')

BTW this command hangs silently if there are no files in the commit that match *.rs which may happen occasionally e.g. if a commit only has markdown files. Something like: [snip]

I think we can probably use cargo fmt in the CI, as that would be simpler.

In the CONTRIBUTING.md file, we might also suggest Vim/Emacs configuration snippets that automatically indent .rs files whenever they're saved. I do that myself, and it's an enormous time saver.

What makes tests valuable and maintainable? Where would you like them adding in the codebase e.g. on a per routing protocol basis?

The following wiki page provides some guidance on that:
https://github.com/holo-routing/holo/wiki/Writing-New-Features#step-3-extend-the-packet-module
https://github.com/holo-routing/holo/wiki/Writing-New-Features#step-9-write-conformance-tests

We also have a dedicated wiki page for conformance testing: https://github.com/holo-routing/holo/wiki/Data-Driven-Testing

I think CONTRIBUTING.md could provide a high-level overview of testing and point to those wiki pages for details.

Perhaps this is outside the scope of this request, nonetheless if contributors are able to run holo and test it as a system that may help increase the confidence their contributions don't break holo (and might even improve its behaviour :) )

We already have pre-configured network topologies that can be used to test Holo as a full routing stack, including interop tests with commercial vendors: https://github.com/holo-routing/holo/wiki/Testing-Environment-Setup

I found https://github.com/holo-routing/holo/wiki/Holo-Guide-%E2%80%90-Setting-up-dependencies partly as I was trying to work out why the fuzz test targets don't compile on one of my ubuntu machines where I'm building holo for the first time. (The compilation error is rust-lld: error: unable to find library -lyang but the details are out-of-scope for this ticket). Anyway, is that guide still accurate? e.g. it includes cloning libyang then building and installing it locally.

Building and installing libyang isn't required unless the yang3_bundled feature is disabled (it's enabled by default). I haven't had a chance to read Paul's guide yet, but I've just updated the section where it says libyang needs to be installed.

Regarding the -lyang error, I noticed the fuzz targets are using dynamic linking for libyang:

$ ldd fuzz/target/x86_64-unknown-linux-gnu/release/bgp_message_decode | grep libyang
        libyang.so.3 => /usr/local/lib/libyang.so.3 (0x00007f4a27024000)

I'll push a fix for this later today. Thanks for reporting it!