|
1 | | -# Contributing to TM1Py |
| 1 | +# Contributing to TM1py |
2 | 2 |
|
3 | | -Thank you for your interest in contributing to TM1Py! This document provides guidelines and information about the contribution process. |
| 3 | +TM1py is an open-source project. It thrives on contributions from the TM1 community. |
4 | 4 |
|
5 | | -## Table of Contents |
6 | | -- [Getting Started](#getting-started) |
7 | | -- [Development Setup](#development-setup) |
8 | | -- [Making Changes](#making-changes) |
9 | | -- [Pull Request Process](#pull-request-process) |
10 | | -- [Release Process](#release-process) |
11 | | -- [Code Style](#code-style) |
| 5 | +To ensure a smooth and consistent contribution process, please review our full contributor guide: |
12 | 6 |
|
13 | | -## Getting Started |
| 7 | +👉 **See the complete guide here:** [`docs/how-to-contribute.md`](docs/how-to-contribute.md) |
14 | 8 |
|
15 | | -1. Fork the repository |
16 | | -2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/tm1py.git` |
17 | | -3. Add upstream remote: `git remote add upstream https://github.com/cubewise-code/tm1py.git` |
18 | | - |
19 | | -## Development Setup |
20 | | - |
21 | | -1. **Create a virtual environment:** |
22 | | - ```bash |
23 | | - python -m venv venv |
24 | | - source venv/bin/activate # On Windows: venv\Scripts\activate |
25 | | - ``` |
26 | | - |
27 | | -2. **Install TM1Py in development mode:** |
28 | | - ```bash |
29 | | - pip install -e .[pandas,dev] |
30 | | - ``` |
31 | | - |
32 | | -3. **Install development tools:** |
33 | | - ```bash |
34 | | - pip install black ruff pytest |
35 | | - ``` |
36 | | - |
37 | | -## Making Changes |
38 | | - |
39 | | -1. **Create a branch:** |
40 | | - ```bash |
41 | | - git checkout -b your-feature-name |
42 | | - ``` |
43 | | - |
44 | | -2. **Make your changes** following the code style guidelines |
45 | | - |
46 | | -3. **Format your code:** |
47 | | - ```bash |
48 | | - black . |
49 | | - ruff check --fix . |
50 | | - ``` |
51 | | - |
52 | | -4. **Test your changes** (if you have access to a TM1 instance): |
53 | | - ```bash |
54 | | - pytest Tests/ |
55 | | - ``` |
56 | | - |
57 | | -## Pull Request Process |
58 | | - |
59 | | -### 1. Before Opening a PR |
60 | | - |
61 | | -- Ensure your code follows the style guidelines |
62 | | -- Run formatting tools (Black, Ruff) |
63 | | -- Update documentation if needed |
64 | | -- Write clear, descriptive commit messages |
65 | | - |
66 | | -### 2. Opening a PR |
67 | | - |
68 | | -- Push your branch to your fork |
69 | | -- Open a PR against the `master` branch |
70 | | -- Fill out the PR template (if available) |
71 | | -- Describe what your PR does and why |
72 | | - |
73 | | -**Note**: You don't need to follow any special commit message format! Maintainers will handle versioning via labels. |
74 | | - |
75 | | -### 3. PR Validation |
76 | | - |
77 | | -Your PR will automatically trigger validation checks: |
78 | | -- **Code formatting** (Black) |
79 | | -- **Linting** (Ruff) |
80 | | -- **Future**: Unit tests (when available) |
81 | | - |
82 | | -These checks must pass before your PR can be merged. |
83 | | - |
84 | | -### 4. Review Process |
85 | | - |
86 | | -- Maintainers will review your PR |
87 | | -- Address any feedback or requested changes |
88 | | -- Once approved, a maintainer will add the appropriate release label and merge |
89 | | - |
90 | | -## Release Process |
91 | | - |
92 | | -TM1Py uses **automated nightly releases** with semantic versioning. |
93 | | - |
94 | | -### For Contributors |
95 | | - |
96 | | -**You don't need to do anything special!** Just: |
97 | | -1. Create your PR |
98 | | -2. Wait for review |
99 | | -3. That's it! |
100 | | - |
101 | | -No need for special: |
102 | | -- Commit message formats |
103 | | -- Branch naming conventions |
104 | | -- Version bumping |
105 | | -- Release notes |
106 | | - |
107 | | -### For Maintainers |
108 | | - |
109 | | -**IMPORTANT**: Before merging a PR, you must add the appropriate label to control the version bump. |
110 | | - |
111 | | -| Label | Version Bump | When to Use | Example | |
112 | | -|-------|--------------|-------------|---------| |
113 | | -| `release:patch` | `2.1.5` → `2.1.6` | Bug fixes, small improvements | Fix pandas compatibility issue | |
114 | | -| `release:minor` | `2.1.5` → `2.2.0` | New features, enhancements | Add support for new TM1 REST API endpoint | |
115 | | -| `release:major` | `2.1.5` → `3.0.0` | Breaking changes, major updates | Remove deprecated methods, change API | |
116 | | -| `skip-release` (or no label) | No version bump | Docs, tests, CI changes, or changes you don't want to release yet | Update README, fix typo in docs | |
117 | | - |
118 | | -**Default behavior**: If no label is added, **NO release will be created**. This is a safe default to prevent accidental releases. |
119 | | - |
120 | | -**To create a release**: You must explicitly add `release:patch`, `release:minor`, or `release:major` label. |
121 | | - |
122 | | -### Release Timeline |
123 | | - |
124 | | -**Daily cycle:** |
125 | | -``` |
126 | | -Day 1: |
127 | | - 10:00 AM - PR #123 (bug fix, labeled 'release:patch') merged |
128 | | - 2:00 PM - PR #124 (feature, labeled 'release:minor') merged |
129 | | - 5:00 PM - PR #125 (docs update, no label) merged |
130 | | -
|
131 | | - 4:00 AM (next day) - Nightly workflow starts: |
132 | | - - Runs full integration tests (2-3 hours) |
133 | | - - If tests pass: |
134 | | - → Creates release 2.2.0 (because of the minor label) |
135 | | - → Publishes to PyPI (includes all 3 PRs) |
136 | | - → Updates documentation |
137 | | - 7:00 AM - Users can: pip install --upgrade TM1py |
138 | | -
|
139 | | -Day 2: |
140 | | - 11:00 AM - PR #126 (minor fix, no label) merged |
141 | | - 3:00 PM - PR #127 (test update, no label) merged |
142 | | -
|
143 | | - 4:00 AM (next day) - Nightly workflow starts: |
144 | | - - No release labels found |
145 | | - - Skips release (no version bump, no PyPI publish) |
146 | | -``` |
147 | | - |
148 | | -### How It Works |
149 | | - |
150 | | -1. **Merge to master** → PR is merged after validation passes |
151 | | -2. **Nightly at 4 AM CET** → Automated workflow runs: |
152 | | - - Checks for new commits since last release |
153 | | - - Runs full integration test suite |
154 | | - - Determines version bump from PR labels |
155 | | - - Creates GitHub Release |
156 | | - - Publishes to PyPI |
157 | | -3. **Next morning** → New version available to users! |
158 | | - |
159 | | -## Code Style |
160 | | - |
161 | | -### Python Code Style |
162 | | - |
163 | | -- **Line length**: 120 characters (configured in Black) |
164 | | -- **Formatting**: Use Black for automatic formatting |
165 | | -- **Linting**: Use Ruff for import sorting and error detection |
166 | | -- **Target version**: Python 3.7+ |
167 | | - |
168 | | -### Running Code Style Tools |
169 | | - |
170 | | -```bash |
171 | | -# Format code |
172 | | -black . |
173 | | - |
174 | | -# Check imports and linting |
175 | | -ruff check . |
176 | | - |
177 | | -# Auto-fix linting issues |
178 | | -ruff check --fix . |
179 | | -``` |
180 | | - |
181 | | -### Import Organization |
182 | | - |
183 | | -Imports should be organized by Ruff/isort: |
184 | | -1. Standard library imports |
185 | | -2. Third-party imports |
186 | | -3. Local application imports |
187 | | - |
188 | | -Example: |
189 | | -```python |
190 | | -import os |
191 | | -from typing import List |
192 | | - |
193 | | -import requests |
194 | | -from requests.auth import HTTPBasicAuth |
195 | | - |
196 | | -from TM1py.Objects import Cube |
197 | | -from TM1py.Services import TM1Service |
198 | | -``` |
199 | | - |
200 | | -## Testing |
201 | | - |
202 | | -### Running Tests |
203 | | - |
204 | | -If you have access to TM1 instances: |
205 | | - |
206 | | -```bash |
207 | | -# Run all tests |
208 | | -pytest Tests/ |
209 | | - |
210 | | -# Run specific test file |
211 | | -pytest Tests/test_cube_service.py |
212 | | - |
213 | | -# Run with verbose output |
214 | | -pytest Tests/ -v |
215 | | -``` |
216 | | - |
217 | | -### Test Configuration |
218 | | - |
219 | | -Tests require TM1 connection configuration. See `Tests/resources/` for setup instructions. |
220 | | - |
221 | | -## Questions? |
222 | | - |
223 | | -- Check existing [Issues](https://github.com/cubewise-code/tm1py/issues) |
224 | | -- Review [Discussions](https://github.com/cubewise-code/tm1py/discussions) |
225 | | -- Read the [Documentation](https://tm1py.readthedocs.io/) |
226 | | - |
227 | | -## License |
228 | | - |
229 | | -By contributing, you agree that your contributions will be licensed under the MIT License. |
230 | | - |
231 | | ---- |
232 | | - |
233 | | -Thank you for contributing to TM1Py! 🎉 |
| 9 | +If you have questions or need help at any stage, feel free to open an issue or start a discussion. |
0 commit comments