Dev-iL commented on code in PR #1529: URL: https://github.com/apache/hamilton/pull/1529#discussion_r3005715488
########## scripts/README.md: ########## @@ -0,0 +1,290 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + +# Policy on source versus distribution + +Apache Hamilton is an apache-incubating project. As such, we intend to follow all Apache guidelines to +both the spirit (and when applicable) the letter. + +That said, there is occasional ambiguity. Thus we aim to clarify with a reasonable and consistently maintained +approach. The question that we found most ambiguous when determining our release process is: +1. What counts as source code, and should thus be included in the "sdist" (the source-only distribution) +2. What should be included in the build? + +Specifically, we set the following guidelines: + +| | source (to vote on) -- tar.gz | sdist -- source used to build | whl file | Reasoning | +|---|---|---|---|---| +| Build Scripts | Y | Y | N | Included in tar.gz and sdist as they are needed to reproduce the build, but not in the whl. These are only meant to be consumed by developers/pod members. | +| Library Source code | Y | Y | Y | Core library source code is included in all three distributions: tar.gz, sdist, and whl. | +| Tests (unit + plugin) | Y | Y | N | We expect users/PMC to download the source distribution, build from source, run the tests, and validate. Thus we include in the tar.gz and sdist, but not in the whl. | +| READMEs | Y | Y | Y | Standard project metadata files (README.md, LICENSE, NOTICE, DISCLAIMER) are included in all three distributions. | +| Documentation | Y | N | N | Documentation source is included in the tar.gz for voters to review, but not in the sdist or whl as it is not needed for building or using the package. | +| Representative Examples | Y | Y | N | A curated set of examples are included in tar.gz and sdist so voters can verify Hamilton works end-to-end. Not in the whl as they serve as documentation/verification only. | +| Other Examples | Y | N | N | These are included in the tar.gz for voters to review but not included in the sdist or whl. | + +# Packages + +Apache Hamilton consists of 5 independently versioned packages: + +| Package | Key | Working Directory | Description | +|---|---|---|---| +| `apache-hamilton` | `hamilton` | `.` | Core library (must be released first) | +| `apache-hamilton-sdk` | `sdk` | `ui/sdk` | Tracking SDK | +| `apache-hamilton-contrib` | `contrib` | `contrib` | Community dataflows | +| `apache-hamilton-ui` | `ui` | `ui/backend` | Web UI server | +| `apache-hamilton-lsp` | `lsp` | `dev_tools/language_server` | Language server | + +The core `apache-hamilton` package must be released first. The other four packages depend on it but not on each other. + +# Release Process + +## Environment Setup + +We recommend using [uv](https://docs.astral.sh/uv/) for Python environment management. It handles Python versions, virtual environments, and dependency installation in a single tool. + +### Prerequisites + +- Python 3.10+ +- `uv` ([install guide](https://docs.astral.sh/uv/getting-started/installation/)) +- `flit` for building +- `twine` for package validation +- GPG key configured for signing +- Node.js + npm for UI builds (only needed for the `ui` package) +- Apache RAT jar for license checking (optional, for verification) + +```bash +# Install uv (if not already installed) +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Create a virtual environment with build dependencies +uv venv --python 3.11 +uv pip install flit twine Review Comment: Perhaps uv sync with a "build-tools" group? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
