Contributing

We welcome contributions to WinFsp-MemFs-Extended. This guide will help you understand the project’s standards and contribution process.

​

Code of conduct

By participating in this project, you agree to maintain a respectful and collaborative environment. Focus on constructive feedback and helping improve the project for everyone.

​

Getting started

Before contributing:

1. Fork the repository on GitHub
2. Clone your fork locally
3. Set up your development environment following the building guide
4. Create a new branch for your changes

​

Code style

WinFsp-MemFs-Extended is written in modern C++ with specific style conventions.

​

Language standards

The project uses C++20 (/std:c++20). You should leverage modern C++ features:

• Smart pointers (std::unique_ptr, std::shared_ptr) instead of raw pointers
• RAII (Resource Acquisition Is Initialization) for resource management
• Move semantics for efficient object transfers
• Standard library containers (std::vector, std::map, etc.)
• Range-based for loops where appropriate
• auto for type deduction when it improves readability

​

Memory safety

Memory safety is critical:

• Always use smart pointers for dynamic memory allocation
• Avoid manual new/delete operations
• Use RAII patterns to ensure resources are properly released
• Prefer stack allocation over heap allocation when possible
• Use containers like std::vector instead of manual array management

​

Thread safety

The filesystem must handle concurrent operations safely:

• Use appropriate synchronization primitives (mutexes, locks)
• Document which data structures require locking
• Avoid data races and undefined behavior
• Test concurrent operations thoroughly using ConcurrencyStressTester

​

Naming conventions

Follow the existing naming patterns in the codebase:

• Use descriptive names that clearly indicate purpose
• Maintain consistency with surrounding code
• Follow C++ standard library naming conventions

​

Code organization

The project is organized into focused modules:

• main.cpp - Entry point and CLI argument parsing
• memfs.h / memfs-interface.h - Core filesystem interface
• nodes.cpp / nodes.h - File and directory node management
• io.cpp - I/O operations (read, write)
• create.cpp / filecreate.cpp - File creation operations
• fileinfo.cpp / dirinfo.cpp - File and directory information
• security.cpp - Security and permissions
• exceptions.h / exceptions.cpp - Error handling
• Additional specialized modules for specific functionality

When adding new functionality:

• Place code in the appropriate module
• Create new modules for substantial new features
• Keep modules focused on a single responsibility

​

Testing requirements

All contributions must be thoroughly tested before submission.

​

Required testing

You must test your changes with:

1. RandomFilesTester - Verify basic file operations work correctly
   RandomFilesTester.exe R:\test 1000
   
2. ConcurrencyStressTester - Ensure thread-safety with all procedures
   ConcurrencyStressTester.exe 60 all
   
3. Manual testing - Test real-world usage scenarios:
   • Copying files to/from the RAM disk
   • Running applications from the RAM disk
   • Using Windows Explorer and file operations
   • Testing edge cases specific to your changes

​

Testing for bug fixes

If fixing a bug:

1. Create a test case that reproduces the bug
2. Verify the test fails without your fix
3. Verify the test passes with your fix
4. Run all existing tests to ensure no regressions

​

Testing for new features

If adding a new feature:

1. Create comprehensive tests covering normal usage
2. Test edge cases and error conditions
3. Test interaction with existing features
4. Verify performance impact is acceptable

​

License

WinFsp-MemFs-Extended is licensed under GPL-3.0 (GNU General Public License version 3).

​

What this means for contributors

By submitting a contribution, you agree that:

• Your contribution will be licensed under GPL-3.0
• Your contribution is your original work or you have rights to submit it
• You understand that GPL-3.0 is a copyleft license
• Any modifications must also be released under GPL-3.0

​

GPL-3.0 key points

• Freedom to use: Anyone can use the software for any purpose
• Freedom to study: Source code must remain available
• Freedom to modify: Anyone can modify the software
• Freedom to distribute: Anyone can distribute copies
• Copyleft: Derivative works must also be GPL-3.0

Read the full license text in the LICENSE file in the repository.

​

Important licensing notes

• You cannot incorporate this code into proprietary/closed-source software
• Any software that links to or modifies this code must also be GPL-3.0
• If you distribute modified versions, you must provide source code
• You must preserve all copyright and license notices

​

Pull request process

Follow these steps to submit your contribution:

​

1. Prepare your changes

• Create a new branch from main with a descriptive name:
  git checkout -b feature/add-compression-support
  git checkout -b fix/memory-leak-in-io
  
• Make your changes following the code style guidelines
• Test thoroughly using the testing utilities
• Commit your changes with clear, descriptive messages:
  git commit -m "Add support for transparent file compression"
  git commit -m "Fix memory leak in IO operation cleanup"
  

​

2. Ensure code quality

Before submitting:

• Code compiles without warnings in both Debug and Release configurations
• All tests pass (RandomFilesTester, ConcurrencyStressTester)
• Code follows the project’s style conventions
• Memory leaks have been checked and resolved
• Thread-safety has been verified for concurrent operations
• Documentation has been updated if needed

​

3. Create the pull request

1. Push your branch to your fork:
   git push origin feature/add-compression-support
   
2. Open a pull request on GitHub
3. Provide a clear description including:
   • What changes you made
   • Why you made them (what problem does it solve?)
   • How you tested the changes
   • Any breaking changes or migration notes
   • Related issue numbers if applicable

​

4. Pull request review

Your pull request will be reviewed for:

• Code quality and adherence to style guidelines
• Correctness and completeness of the implementation
• Test coverage and verification
• Performance implications
• Compatibility with existing functionality
• Documentation clarity

Be responsive to feedback:

• Address review comments promptly
• Update your branch with requested changes
• Ask questions if feedback is unclear
• Be open to suggestions and alternative approaches

​

5. Merging

Once approved:

• Your pull request will be merged into the main branch
• Your contribution will be included in the next release
• You’ll be credited as a contributor

​

Reporting issues

If you find a bug but aren’t ready to fix it yourself:

1. Check if the issue already exists in the issue tracker
2. Create a new issue with:
   • Clear description of the problem
   • Steps to reproduce
   • Expected vs. actual behavior
   • System information (Windows version, WinFsp version)
   • Relevant logs or error messages

​

Getting help

If you need help with development:

• Review the existing codebase for examples
• Check the WinFsp documentation for filesystem concepts
• Open an issue to discuss significant changes before implementing
• Ask questions in pull request discussions

​

Recognition

Contributors are valued members of the project. Your contributions help make WinFsp-MemFs-Extended better for everyone. Thank you for your time and effort.