From ebe0e9aa410ea5d3442330deee02e2cc3f2c5985 Mon Sep 17 00:00:00 2001 From: Val Brodsky Date: Mon, 13 May 2024 16:09:32 -0700 Subject: [PATCH 1/4] Add (temp) new version of CONTRIBUTING --- CONTRIBUTING_new.md | 97 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 CONTRIBUTING_new.md diff --git a/CONTRIBUTING_new.md b/CONTRIBUTING_new.md new file mode 100644 index 000000000..7e6fc29c9 --- /dev/null +++ b/CONTRIBUTING_new.md @@ -0,0 +1,97 @@ +# Contribution Guide + +## Our Contribution Goals +We appreciate every contribution. This guide is designed to facilitate easy contributions from SDK users, AI engineers, machine-learning engineers, and software developers in the following areas: + +- **Notebooks (Examples):** Implement practical use cases and solutions other can use too. +- **Code Documentation:** Enhance documentation within this repository, including docstrings and code comments. +- **Test Cases:** Develop tests to ensure code reliability. +- **Bug Fixes:** Help to identify and resolve issues. +- **Feature Improvements:** Optimize and enhance current functionalities. +- **New Features and Extensions:** Innovate and expand our capabilities. + +Additional Ways to Contribute: + +- Bug Reporting: Help us identify issues. +- Suggestions for Improvements: Propose ways to enhance our tools. +- Feature Requests: Let us know what additional functionalities you’d like to see. + +We look forward to your contributions! + +## Table of Contents + +- [General Guidelines](#general-guidelines) +- [Branches and Tags](#branches-and-tags) +- [Release Steps](#release-steps) +- [Github Workflows](#github-workflows) +- [General Prerequisites](#general-prerequisites) +- [Setup and Building](#setup-and-building) +- [Testing](#testing) +- [Documentation](#documentation) + +## General Guidelines + +* For feature requests, we recommend consulting with [Labelbox Support](https://docs.labelbox.com/docs/contacting-customer-support) support or creating a [Github Issue](https://github.com/Labelbox/labelbox-python/issues). +* Ensure that any new libraries added are compliant with the Apache license that governs the repository. +* Ensure that you update any relevant docstrings and comments within the code you may add or change. +* Ensure that any new Python components, such as classes, packages, or methods, that need to feature in the Labelbox documentation have entries in the file [index.rst](https://github.com/Labelbox/labelbox-python/blob/develop/docs/source/index.rst). + +## Branches and Tags + +* All development happens in feature branches ideally prefixed by contributor's initials. For example `fs/feature_name`. +* Approved PRs are merged to the `develop` branch. +* All releases align to a git tag. + +## Release Steps + +Your contributions will be released as soon as it is approved and merged into the `develop` branch. Please consult the [Labelbox](https://docs.labelbox.com/docs/contacting-customer-support) team for if you need a more specific timeframe of when your contributions may be released. + +## Github Workflows + +![workflow](./docs/github-workflow.svg) + +The above shows the Github workflows that currently exist in the repository. + +* Github Branch Workflow + * When you push to a branch, it will create a build of the SDK that runs tests against **staging**. It will publish the build to `test.pypi.org` which can be downloaded for testing. Also, a docker image is built which can be used for testing as it has the SDK installed. +* Github Develop Workflow + * When you push to a `develop` (main branch), it will create a build of the SDK that runs tests against **staging**. It will publish the build to `test.pypi.org` which can be downloaded for testing. Also, a docker image is built which can be used for testing as it has the SDK installed. This docker image is tagged with `develop`. +* Github Publish Workflow + * When you run the publish workflow, it will create a build of the SDK that runs tests against **production**. It will publish the build to `pypi.org` which is what consumers of the SDK will normally use. Also, a docker image is built which can be used for testing as it has the SDK installed. This docker image is tagged with `latest`. + +## General Prerequisites + +[Rye](https://rye-up.com/) must be installed before contributing to the repository as it is the tool used to managed the repository. + +To understand why Rye was chosen, see [here](https://alpopkes.com/posts/python/packaging_tools/). TLDR: Environment, Package, Python, management along with Package publishing and Package building is unified under a single tool for consistency of development. + +If you want to not deal with setting up `Rye`, feel free to use one of [Docker containers](https://github.com/Labelbox/labelbox-python/pkgs/container/labelbox-python) Labelbox has built which contains the entire with `Rye` setup. + +**You can use Poetry to manage the virtual environment.** There's nothing blocking you from using Poetry to manage the virtual environment as the standard `pyproject.toml` format is used, but you'll have to deal with managing Python yourself + be asked not to check in any `poetry.lock` files. Also, you'll have to run equivalent poetry commands that may not be listed in the documentation to perform the same general operations (testing, building, etc.). + +## Setup and Building + +These are general steps that all modules in `libs/` adhere to given the prerequisite of the installation of `Rye` that are needed to setup a module for development and build it. + +* `rye sync` in the module folder you want to work on (EG `rye sync --all-features` to work on `labelbox`). +* `rye build` to create a distribution in `dist/` which you can install into a Python environment (EG `pip install dist/labelbox-build.tar.gz`). + +It is generally **not** recommended to do `pip install -e .` with any Labelbox module to avoid virtual environment pollution. If you want to modify any module while making it compatible with your existing `pip` based projects, build a distribution and install it in your `pip` environment. + +## Testing + +Each module within the repository will generally expected to implement three commands for testing: unit testing, integration testing, and linting/formatting. See the details in each module's `README.md` for more information. + +```bash +rye run unit +rye run integration +rye run lint +``` + +## Documentation + +To generate documentation for all modules (`ReadTheDocs`), run the following command in the root of the repository. + +```bash +rye run docs +``` \ No newline at end of file From 92b5251051a0f8ee5bdf822b37375a1e67ebb7f6 Mon Sep 17 00:00:00 2001 From: Val Brodsky Date: Mon, 13 May 2024 17:44:52 -0700 Subject: [PATCH 2/4] More updates --- CONTRIBUTING_new.md | 118 +++++++++++++++----------------------------- 1 file changed, 41 insertions(+), 77 deletions(-) diff --git a/CONTRIBUTING_new.md b/CONTRIBUTING_new.md index 7e6fc29c9..2d3759bfa 100644 --- a/CONTRIBUTING_new.md +++ b/CONTRIBUTING_new.md @@ -18,80 +18,44 @@ Additional Ways to Contribute: We look forward to your contributions! -## Table of Contents - -- [General Guidelines](#general-guidelines) -- [Branches and Tags](#branches-and-tags) -- [Release Steps](#release-steps) -- [Github Workflows](#github-workflows) -- [General Prerequisites](#general-prerequisites) -- [Setup and Building](#setup-and-building) -- [Testing](#testing) -- [Documentation](#documentation) - -## General Guidelines - -* For feature requests, we recommend consulting with [Labelbox Support](https://docs.labelbox.com/docs/contacting-customer-support) support or creating a [Github Issue](https://github.com/Labelbox/labelbox-python/issues). -* Ensure that any new libraries added are compliant with the Apache license that governs the repository. -* Ensure that you update any relevant docstrings and comments within the code you may add or change. -* Ensure that any new Python components, such as classes, packages, or methods, that need to feature in the Labelbox documentation have entries in the file [index.rst](https://github.com/Labelbox/labelbox-python/blob/develop/docs/source/index.rst). - -## Branches and Tags - -* All development happens in feature branches ideally prefixed by contributor's initials. For example `fs/feature_name`. -* Approved PRs are merged to the `develop` branch. -* All releases align to a git tag. - -## Release Steps - -Your contributions will be released as soon as it is approved and merged into the `develop` branch. Please consult the [Labelbox](https://docs.labelbox.com/docs/contacting-customer-support) team for if you need a more specific timeframe of when your contributions may be released. - -## Github Workflows - -![workflow](./docs/github-workflow.svg) - -The above shows the Github workflows that currently exist in the repository. - -* Github Branch Workflow - * When you push to a branch, it will create a build of the SDK that runs tests against **staging**. It will publish the build to `test.pypi.org` which can be downloaded for testing. Also, a docker image is built which can be used for testing as it has the SDK installed. -* Github Develop Workflow - * When you push to a `develop` (main branch), it will create a build of the SDK that runs tests against **staging**. It will publish the build to `test.pypi.org` which can be downloaded for testing. Also, a docker image is built which can be used for testing as it has the SDK installed. This docker image is tagged with `develop`. -* Github Publish Workflow - * When you run the publish workflow, it will create a build of the SDK that runs tests against **production**. It will publish the build to `pypi.org` which is what consumers of the SDK will normally use. Also, a docker image is built which can be used for testing as it has the SDK installed. This docker image is tagged with `latest`. - -## General Prerequisites - -[Rye](https://rye-up.com/) must be installed before contributing to the repository as it is the tool used to managed the repository. - -To understand why Rye was chosen, see [here](https://alpopkes.com/posts/python/packaging_tools/). TLDR: Environment, Package, Python, management along with Package publishing and Package building is unified under a single tool for consistency of development. - -If you want to not deal with setting up `Rye`, feel free to use one of [Docker containers](https://github.com/Labelbox/labelbox-python/pkgs/container/labelbox-python) Labelbox has built which contains the entire with `Rye` setup. - -**You can use Poetry to manage the virtual environment.** There's nothing blocking you from using Poetry to manage the virtual environment as the standard `pyproject.toml` format is used, but you'll have to deal with managing Python yourself + be asked not to check in any `poetry.lock` files. Also, you'll have to run equivalent poetry commands that may not be listed in the documentation to perform the same general operations (testing, building, etc.). - -## Setup and Building - -These are general steps that all modules in `libs/` adhere to given the prerequisite of the installation of `Rye` that are needed to setup a module for development and build it. - -* `rye sync` in the module folder you want to work on (EG `rye sync --all-features` to work on `labelbox`). -* `rye build` to create a distribution in `dist/` which you can install into a Python environment (EG `pip install dist/labelbox-build.tar.gz`). - -It is generally **not** recommended to do `pip install -e .` with any Labelbox module to avoid virtual environment pollution. If you want to modify any module while making it compatible with your existing `pip` based projects, build a distribution and install it in your `pip` environment. - -## Testing - -Each module within the repository will generally expected to implement three commands for testing: unit testing, integration testing, and linting/formatting. See the details in each module's `README.md` for more information. - -```bash -rye run unit -rye run integration -rye run lint -``` - -## Documentation - -To generate documentation for all modules (`ReadTheDocs`), run the following command in the root of the repository. - -```bash -rye run docs -``` \ No newline at end of file +## Notebooks +Our notebooks contain practical examples for labelbox sdk uses. To update a notebook, +- Creating a new issue you will address or assign an existing issue to yourself here https://github.com/Labelbox/labelbox-python/issues +- Create a new branch using our +- Update or create a new notebook +- Test your changes +- Submit a PR +- Merge code: use default github button (or labelbox engineer may merge it too) + +## Code documentation +- Create a new branch using our +- Update code documentation +- Submit a PR +- Merge code: use default github button (or labelbox engineer may merge it too) + +## Test cases +- Create a new branch using our +- Implement or update a new test +- Submit a PR +- Merge code: use default github button (or labelbox engineer may merge it too) + +## Bug fixing +- Creating a new issue you will address or assign an existing issue to yourself here https://github.com/Labelbox/labelbox-python/issues +- Create a new branch using our +- Implement a fix +- If necessary, add a unit or an integration test +- Update code documentation +- Submit a PR +- Merge code: use default github button (or labelbox engineer may merge it too) + +## Feature optimization / improvements +- Creating a new issue you will address or assign an existing issue to yourself here https://github.com/Labelbox/labelbox-python/issues +- Create a new branch using our +- Implement a code update +- Add or update a unit or an integration test +- Update code documentation +- Submit a PR +- Merge code: use default github button (or labelbox engineer may merge it too) + +## New Features and Extensions +- Coming up in the future \ No newline at end of file From 9c7592a645c6d0fc395f6b40649ad533efae1c0a Mon Sep 17 00:00:00 2001 From: Val Brodsky Date: Tue, 14 May 2024 13:16:26 -0700 Subject: [PATCH 3/4] More updates --- CONTRIBUTING_new.md | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING_new.md b/CONTRIBUTING_new.md index 2d3759bfa..6da1c18dd 100644 --- a/CONTRIBUTING_new.md +++ b/CONTRIBUTING_new.md @@ -58,4 +58,37 @@ Our notebooks contain practical examples for labelbox sdk uses. To update a note - Merge code: use default github button (or labelbox engineer may merge it too) ## New Features and Extensions -- Coming up in the future \ No newline at end of file +- Coming up in the future + + +## Helpful steps +### Branches and Tags +* Begin by creating a branch off the develop branch. +* All development should occur in feature branches, ideally prefixed with the contributor's initials. For example, use `fs/feature_name` for a feature branch. +* Once a PR is approved, merge it into the develop branch using the standard GitHub _PR merge button_ s labeled Merge pull request. This action will squash all commits. +* Ensure that you review all comments thoroughly and make necessary edits or deletions before completing the merge. + + + +### Internal Code Documentation Update + +Our internal developer documentation is generated from Python docstrings and hosted on [ReadTheDocs](https://readthedocs.org/projects/labelbox-python/) using Sphinx. + +Docstrings should be formatted according to the guidelines found [here](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html). + +Unless you're adding a new package or file, documentation updates are automated. You can review your updated documentation by running the following command at the root of the repository: +```bash +rye run docs +``` + +After running the command, navigate to `docs/build/html` and open the index.html file to confirm that your documentation updates are reflected: +```bash +open index.html +``` + +**Adding New Packages:** +If you add a new package, you must update the Sphinx configuration: +* Add the new package to docs/labelbox/index.rst. +* Create a new .rst file for the new package. + +Re-run the documentation command to generate the updated docs and verify your changes. From 1574d57453103f4831d0392936f56209325433c9 Mon Sep 17 00:00:00 2001 From: Val Brodsky Date: Tue, 14 May 2024 15:33:04 -0700 Subject: [PATCH 4/4] Another update --- CONTRIBUTING_new.md | 26 +++++++++++--------------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING_new.md b/CONTRIBUTING_new.md index 6da1c18dd..cd745187c 100644 --- a/CONTRIBUTING_new.md +++ b/CONTRIBUTING_new.md @@ -18,26 +18,18 @@ Additional Ways to Contribute: We look forward to your contributions! -## Notebooks -Our notebooks contain practical examples for labelbox sdk uses. To update a notebook, -- Creating a new issue you will address or assign an existing issue to yourself here https://github.com/Labelbox/labelbox-python/issues -- Create a new branch using our -- Update or create a new notebook -- Test your changes -- Submit a PR -- Merge code: use default github button (or labelbox engineer may merge it too) ## Code documentation - Create a new branch using our - Update code documentation -- Submit a PR -- Merge code: use default github button (or labelbox engineer may merge it too) +- Submit a PR +- Merge code ## Test cases - Create a new branch using our - Implement or update a new test -- Submit a PR -- Merge code: use default github button (or labelbox engineer may merge it too) +- Submit a PR +- Merge code ## Bug fixing - Creating a new issue you will address or assign an existing issue to yourself here https://github.com/Labelbox/labelbox-python/issues @@ -45,7 +37,7 @@ Our notebooks contain practical examples for labelbox sdk uses. To update a note - Implement a fix - If necessary, add a unit or an integration test - Update code documentation -- Submit a PR +- Submit a PR - Merge code: use default github button (or labelbox engineer may merge it too) ## Feature optimization / improvements @@ -54,11 +46,15 @@ Our notebooks contain practical examples for labelbox sdk uses. To update a note - Implement a code update - Add or update a unit or an integration test - Update code documentation -- Submit a PR +- Submit a PR - Merge code: use default github button (or labelbox engineer may merge it too) ## New Features and Extensions -- Coming up in the future +- Contact us for more info + +## Notebooks +Our notebooks contain practical examples for labelbox sdk uses. To update a notebook, +- Contact us for more info ## Helpful steps