diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..afe5bf8 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,38 @@ +# EditorConfig is awesome: https://EditorConfig.org + +# top-most EditorConfig file +root = true + +# Unix-style newlines with a newline ending every file +[*] +end_of_line = lf +insert_final_newline = true +charset = utf-8 +trim_trailing_whitespace = true + +# Bash scripts +[bin/m] +indent_style = space +indent_size = 2 + +# Markdown files +[*.md] +indent_style = space +indent_size = 2 +# Don't enforce max line length in markdown (especially for tables, code blocks) +max_line_length = off + +# JSON files +[*.json] +indent_style = space +indent_size = 2 + +# YAML files +[*.{yml,yaml}] +indent_style = space +indent_size = 2 + +# JavaScript/Node.js files +[*.{js,mjs}] +indent_style = space +indent_size = 2 diff --git a/.github/instructions/README.md b/.github/instructions/README.md new file mode 100644 index 0000000..690e72f --- /dev/null +++ b/.github/instructions/README.md @@ -0,0 +1,67 @@ +# Copilot Instructions + +This directory contains instructions for GitHub Copilot and other AI coding assistants to help maintain code quality and consistency in this repository. + +## Instruction Files + +Each instruction file includes a YAML frontmatter section that specifies which files the instructions apply to using glob patterns. + +### `general.instructions.md` +**Applies to**: `**/*` (all files) + +Provides general context about the project: +- Project overview and characteristics +- Core development principles +- Guidelines for code changes, documentation, and testing +- File organization +- Safety and security practices + +### `m.instructions.md` +**Applies to**: `bin/m` (main Bash script) + +Detailed guidelines for the main Bash executable: +- Style and formatting conventions +- Logging and error handling patterns +- CLI/dispatch conventions +- Version and regex handling +- Networking and downloads +- OS/distro/arch detection +- Filesystem operations and hooks +- Safety and portability checks +- Quick review checklist + +### `docs.instructions.md` +**Applies to**: `/**/*.md` (all Markdown files) + +Documentation-specific guidelines: +- Focus on clarity and accuracy +- Maintain consistency with `.editorconfig` settings +- Special handling for tables, code blocks, and frontmatter + +## Related Files + +### `.editorconfig` +Defines code formatting standards for various file types in the repository. The documentation instructions reference this file to ensure consistency. + +## How It Works + +When GitHub Copilot or similar AI assistants work on files in this repository, they automatically read and apply the relevant instructions based on the `applyTo` patterns. This helps ensure: + +1. **Consistency**: All changes follow established patterns +2. **Safety**: Critical checks and validations are not bypassed +3. **Quality**: Code reviews catch common issues +4. **Context**: AI has necessary background about the project + +## Maintaining Instructions + +When updating these instructions: +1. Keep the YAML frontmatter with `applyTo` patterns +2. Be specific and actionable +3. Include examples where helpful +4. Test that the instructions improve code quality +5. Keep them focused on guidance that can be applied programmatically + +## References + +- [GitHub Copilot Instructions Documentation](https://gh.io/copilot-coding-agent-tips) +- [EditorConfig Specification](https://editorconfig.org) diff --git a/.github/instructions/general.instructions.md b/.github/instructions/general.instructions.md new file mode 100644 index 0000000..0daedb6 --- /dev/null +++ b/.github/instructions/general.instructions.md @@ -0,0 +1,67 @@ +--- +applyTo: "**/*" +--- + +# General Instructions for m Repository + +## About the Project + +`m` is a MongoDB version management tool written in Bash. It helps users download, install, and manage multiple versions of MongoDB server and command-line tools. + +## Key Characteristics + +- **Primary Language**: Bash scripting (bin/m is the main executable) +- **Cross-platform**: Supports Linux and macOS (including Apple Silicon) +- **Package Manager**: Distributed via npm but implemented as a Bash script +- **Testing**: Node.js-based test suite (test/suite.mjs) + +## Core Principles + +1. **Minimal Dependencies**: The tool should work with standard Unix utilities and Bash +2. **Cross-platform Compatibility**: Changes must work on both Linux and macOS +3. **Backward Compatibility**: Preserve existing behavior and CLI interface +4. **Safety First**: Handle errors gracefully, validate inputs, and clean up on failures + +## Development Guidelines + +### Code Changes + +- Follow existing code style and conventions (see file-specific instructions) +- Test on both Linux and macOS when possible +- Ensure all existing tests pass before submitting changes +- Add tests for new functionality when appropriate + +### Documentation + +- Keep README.md up to date with CLI changes +- Use clear, concise language suitable for technical users +- Include examples for new features +- Follow the existing documentation structure and tone + +### Testing + +- Run the test suite with `npm test` before submitting changes +- Test manually with actual MongoDB downloads when modifying installation logic +- Verify cross-platform behavior for platform-specific changes + +## File Organization + +- `bin/m` - Main Bash executable +- `test/` - Node.js test suite +- `.github/instructions/` - Copilot AI instructions for code review +- `README.md` - User-facing documentation +- `CONTRIBUTING.md` - Contribution guidelines + +## Common Tasks + +- **Version Bumping**: Update VERSION variable in bin/m and version in package.json +- **Adding CLI Commands**: Update help text, case statement, and add tests +- **Documentation Updates**: Keep README.md in sync with code changes + +## Safety and Security + +- Never expose credentials or API tokens +- Validate all user inputs +- Use quotes around variables to prevent word splitting issues +- Clean up temporary files and directories on failure +- Check exit codes and handle errors appropriately