Improve code documentation and add contribution guidelines

[dennisklein]

Summary

Enhance project documentation to improve maintainability and contributor experience.

Proposed Additions

Code Documentation

• Add Doxygen-style comments for all public methods
• Document thread-safety guarantees for the plugin
• Explain the only_once pattern and its purpose (main.cpp:219-239)
• Add architectural overview comments in main.cpp
• Document the plugin lifecycle and SPANK callback order

Contributor Documentation

• Create CONTRIBUTING.md
  • Guidelines for contributors
  • Code style requirements (document current conventions)
  • How to run tests locally (expand on tests/README.md)
  • Pull request process
  • How to report bugs

User Documentation (README.md enhancements)

• Add troubleshooting section

  • Common error messages and their solutions
  • Debug mode usage examples (SLURM_SINGULARITY_DEBUG=true)
  • Permission issues guide
  • Container not found scenarios

• Add examples section

  • Real-world use cases
  • Multi-node jobs
  • Job arrays with containers
  • Integration with module system

• Document upgrade path

  • Migration guide between versions
  • Breaking changes policy
  • Slurm compatibility matrix

Benefits

• Easier onboarding for new contributors
• Reduced support burden through self-service troubleshooting
• Better understanding of code architecture