CONTRIBUTING.md

Contributing to DRAM Controller

Thank you for your interest in contributing to the DRAM Controller project! We welcome contributions from the community.

How to Contribute

Reporting Bugs

If you find a bug, please open an issue on GitHub with:

• A clear description of the problem
• Steps to reproduce the issue
• Expected vs. actual behavior
• Simulation waveforms if applicable
• Your environment (OS, tool versions)

Suggesting Enhancements

Enhancement suggestions are welcome! Please open an issue describing:

• The feature you'd like to see
• Why it would be useful
• Possible implementation approach

Pull Requests

1. Fork the repository and create your branch from main

2. Follow the coding style used in the existing codebase:

   • Use consistent indentation (4 spaces)
   • Add module headers with purpose and responsibilities
   • Comment complex logic
   • Follow Verilog naming conventions

3. Add tests for new features:

   • Update or add testbench cases
   • Ensure all tests pass
   • Include waveform verification

4. Update documentation:

   • Update README.md if adding features
   • Update architecture.md for structural changes
   • Add inline comments for complex logic

5. Commit your changes:

   • Use clear, descriptive commit messages
   • Reference issues in commits (e.g., "Fixes #123")

6. Submit the pull request:

   • Describe what your changes do
   • Reference related issues
   • Include test results

Code Style Guidelines

Verilog Style

// Good: Clear module header
// ============================================================================
// Module Name
// ============================================================================
// Purpose: Clear description
// Responsibilities: What it does
// ============================================================================

module example #(
    parameter WIDTH = 8
)(
    input wire clk,
    input wire rst_n,
    output reg [WIDTH-1:0] data_out
);

    // Good: Descriptive section comments
    // ========================================================================
    // Register Declarations
    // ========================================================================
    reg [WIDTH-1:0] counter;
    
    // Good: Explain non-obvious logic
    always @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            counter <= {WIDTH{1'b0}};
        end else begin
            counter <= counter + 1'b1;
        end
    end

endmodule

File Organization

• rtl/: RTL design files only
• rtl/core/: Core controller modules
• rtl/utils/: Utility/helper modules
• tb/: Testbench files
• docs/: Documentation
• scripts/: Build and simulation scripts

Development Process

1. Test your changes:

   cd scripts
   .\simulate.bat

2. Verify no errors:

   • Check simulation output
   • Review waveforms in GTKWave
   • Ensure all tests pass

3. Run lint checks (if available):

   • Use verilator or other linting tools
   • Fix any warnings

Questions?

Feel free to open an issue for any questions about contributing!

License

By contributing, you agree that your contributions will be licensed under the MIT License.