|
| 1 | +# Contributing to Python Environments |
| 2 | + |
| 3 | +Thank you for your interest in contributing to the Python Environments extension! This document provides guidelines and instructions to help you get the project set up and start contributing. |
| 4 | + |
| 5 | +## Code of Conduct |
| 6 | + |
| 7 | +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. |
| 8 | + |
| 9 | +## Contributor License Agreement |
| 10 | + |
| 11 | +This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit <https://cla.opensource.microsoft.com>. |
| 12 | + |
| 13 | +When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. |
| 14 | + |
| 15 | +## Prerequisites |
| 16 | + |
| 17 | +Before setting up your development environment, ensure you have the following installed: |
| 18 | + |
| 19 | +- **Node.js** (v18 or later) - [Download](https://nodejs.org/) |
| 20 | +- **npm** (v9 or later) - Usually included with Node.js |
| 21 | +- **VS Code** - [Download](https://code.visualstudio.com/) |
| 22 | +- **Python** (v3.9 or later) - For testing and running examples |
| 23 | + |
| 24 | +## Getting Started |
| 25 | + |
| 26 | +### 1. Fork and Clone the Repository |
| 27 | + |
| 28 | +### 2. Install Node Dependencies |
| 29 | + |
| 30 | +```bash |
| 31 | +npm install |
| 32 | +``` |
| 33 | + |
| 34 | +This will install all required Node.js packages for the project. |
| 35 | + |
| 36 | +### 3. Set Up Your Python Environment |
| 37 | + |
| 38 | +First, create a Python virtual environment in the project: |
| 39 | + |
| 40 | +```bash |
| 41 | +# Create a virtual environment |
| 42 | +python -m venv .venv |
| 43 | + |
| 44 | +# Activate the virtual environment |
| 45 | +source .venv/bin/activate |
| 46 | + |
| 47 | +# Or on Windows: |
| 48 | +# .\.venv\Scripts\activate |
| 49 | + |
| 50 | +# Install Python project dependencies |
| 51 | +pip install -r requirements.txt |
| 52 | + |
| 53 | +# Or if using dev requirements: |
| 54 | +pip install -r requirements-dev.txt |
| 55 | +``` |
| 56 | + |
| 57 | +This sets up the Python environment used for testing and running the extension. |
| 58 | + |
| 59 | +## Development Workflow |
| 60 | + |
| 61 | +### Building and Watching Files |
| 62 | + |
| 63 | +The project uses webpack for bundling and TypeScript for compilation. To start development: |
| 64 | + |
| 65 | +```bash |
| 66 | +# Start the watch task (compiles and bundles automatically) |
| 67 | +npm run watch |
| 68 | +``` |
| 69 | + |
| 70 | +This command: |
| 71 | +- Watches TypeScript files in `src/` for changes |
| 72 | +- Automatically recompiles on file changes |
| 73 | +- Bundles the extension for testing |
| 74 | + |
| 75 | +You can also run specific npm scripts: |
| 76 | + |
| 77 | +```bash |
| 78 | +npm run compile # Single compilation |
| 79 | +npm run package # Production build with minification |
| 80 | +npm run lint # Run ESLint |
| 81 | +npm run watch-tests # Watch and compile test files |
| 82 | +``` |
| 83 | + |
| 84 | +### Project Structure |
| 85 | + |
| 86 | +``` |
| 87 | +src/ |
| 88 | +├── api.ts # Public extension API definitions |
| 89 | +├── extension.ts # Extension entry point |
| 90 | +├── helpers.ts # Utility functions |
| 91 | +├── internal.api.ts # Internal API |
| 92 | +├── common/ # Core utilities and wrappers |
| 93 | +│ ├── constants.ts |
| 94 | +│ ├── logging.ts |
| 95 | +│ ├── commands.ts |
| 96 | +│ ├── localize.ts # Localization strings |
| 97 | +│ └── ... |
| 98 | +├── features/ # Main extension features |
| 99 | +│ ├── envCommands.ts |
| 100 | +│ ├── envManagers.ts |
| 101 | +│ ├── projectManager.ts |
| 102 | +│ ├── pythonApi.ts |
| 103 | +│ └── ... |
| 104 | +├── managers/ # Environment manager implementations |
| 105 | +│ ├── builtin/ |
| 106 | +│ ├── conda/ |
| 107 | +│ ├── pipenv/ |
| 108 | +│ ├── poetry/ |
| 109 | +│ ├── pyenv/ |
| 110 | +│ └── ... |
| 111 | +└── test/ # Test files |
| 112 | + ├── unittests.ts # Mock setup for unit tests |
| 113 | + ├── constants.ts |
| 114 | + └── ... |
| 115 | +
|
| 116 | +files/ |
| 117 | +├── common_pip_packages.json # Default pip packages |
| 118 | +├── conda_packages.json # Default conda packages |
| 119 | +└── templates/ # Project templates |
| 120 | +
|
| 121 | +docs/ |
| 122 | +└── projects-api-reference.md # API documentation |
| 123 | +``` |
0 commit comments