Metadata-Version: 2.4
Name: eclipse-care
Version: 0.0.2
Summary: Eclipse CLI Assessment and Recommendation Engine
Project-URL: Homepage, https://projects.eclipse.org/projects/technology.dash
Project-URL: Documentation, https://pages.eclipse.dev/eclipse/technology/dash/eclipse-care
Project-URL: Source, https://gitlab.eclipse.org/eclipsefdn/emo-team/eclipse-care
Project-URL: Changelog, https://gitlab.eclipse.org/eclipsefdn/emo-team/eclipse-care/-/blob/main/CHANGELOG.md
Author-email: André Gomes <andre.gomes@eclipse-foundation.org>, Boris Baldassari <boris.baldassari@eclipse-foundation.org>
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Eclipse Public License 2.0 (EPL-2.0)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: colorama==0.4.6
Requires-Dist: pygithub==2.8.1
Requires-Dist: python-gitlab==8.1.0
Requires-Dist: scancode-toolkit-mini==32.5.0
Requires-Dist: typecode-libmagic==5.39.210531
Description-Content-Type: text/markdown

<!--
 * Copyright (c) 2025 The Eclipse Foundation
 * 
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 * 
 * SPDX-FileType: DOCUMENTATION
 * SPDX-FileCopyrightText: 2025 The Eclipse Foundation
 * SPDX-License-Identifier: EPL-2.0
-->

# Eclipse CLI Assessment and Recommendation Engine

![Gitlab Pipeline Status](https://img.shields.io/gitlab/pipeline-status/eclipsefdn%2Femo-team%2Feclipse-care?gitlab_url=https%3A%2F%2Fgitlab.eclipse.org&branch=main)
![PyPI - Version](https://img.shields.io/pypi/v/eclipse-care)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/eclipse-care)
[![Documentation](https://img.shields.io/badge/docs-GitLab_Pages-brightgreen)](https://pages.eclipse.dev/eclipse/technology/dash/eclipse-care)
[![REUSE status](https://api.reuse.software/badge/gitlab.eclipse.org/eclipsefdn/emo-team/eclipse-care)](https://api.reuse.software/info/gitlab.eclipse.org/eclipsefdn/emo-team/eclipse-care)
[![GitLab License](https://img.shields.io/gitlab/license/eclipse%2Ftechnology%2Fdash%2Fip-analysis?gitlab_url=https%3A%2F%2Fgitlab.eclipse.org&color=informational)](https://www.eclipse.org/legal/epl-2.0/)

## Description

Eclipse CARE lets you assess any Eclipse project regarding Eclipse open source best practices,
and get recommendations for improvement. 

Its features include:
* **Recommended files** (e.g. README, LICENSE, SECURITY, etc.) in repositories (Implemented).
* **Copyright headers checks** (Implemented).
* **IP and license management** (Coming Soon).
* **Headers generator** (Coming Soon).

## Resources 

**[Official Documentation](https://pages.eclipse.dev/eclipse/technology/dash/eclipse-care)** - 
Detailed guides, API reference, and architecture.

To learn more about the Eclipse way on open source best practices, see:
* The [Eclipse project handbook](https://www.eclipse.org/projects/handbook/).

The EMO team also provides several trainings, resources and presentations:
* [Eclipse project governance](https://www.eclipse.org/projects/articles/) articles on eclipse.org.
* [Committer training](https://www.eclipse.org/projects/training) resources for developers and maintainers.
* [EMO Office hours](https://www.eclipse.org/projects/calendar#office-hours) to ask us anything!

## Installation

Eclipse CARE requires Python 3.10 or higher. You can install the package directly from PyPI:

```bash
pip install eclipse-care
```

Or from the source:

1. Clone the repository.
2. Get [Hatch](https://hatch.pypa.io/latest/install) to build the tool.
3. Build and install the tool:

```bash
hatch build
pip install dist/eclipse_care-*.whl
```

## Usage

Once installed, you can use the `eclipse-care` command:

**Arguments:**
* `project_id`: The Eclipse project ID to assess (e.g., `technology.dash`).

**Options:**
* `-c, --conf`: path to an `.ini` file containing GitHub/GitLab authentication tokens.
* `-m, --modules`: Specify which modules to run (e.g., `care.legal.recommended_files`).
* `-v, --verbose`: Display more verbose information during execution.
* `-V, --version`: Show the version and exit.

Authentication credentials for GitLab and GitHub can be provided either in a classic `.ini` file (see [the documentation](https://pages.eclipse.dev/eclipse/technology/dash/eclipse-care)) or in environment variables:

* **GH_AUTH_TOKEN:** Your GitHub Personal Access Token.
* **GL_AUTH_TOKEN:** Your GitLab Personal Access Token.

_Please note that, for GitHub API public access, the API rate limits are very low. It's very likely that you'll get
rate limited if you don't provide a **GH_TOKEN**._

## Examples

To analyze a specific project using its ID:
```bash
eclipse-care technology.dash
```

To run with verbose output and a configuration file for credentials:
```bash
eclipse-care technology.dash --conf my_config.ini --verbose
```

To run only a specific module:
```bash
eclipse-care technology.dash --modules care.legal.recommended_files
```

## Support

If you need help or have questions, please use the following channels:
* **Issue Tracker**: Report bugs or request features on our GitLab instance (preferred).
* **Mailing List**: Engage with the community via the Eclipse [dash-dev mailing list](https://accounts.eclipse.org/mailing-list/dash-dev).

## Contributing

We are open to contributions! We recommend the following workflow:

* Submit an issue describing the feature or bug.
* Fork the repository and submit a MR. 

We aim to review issues and code, and provide feedback diligently.

See the full documentation in the docs/ directory for more information about the coding guidelines and expected 
resources (e.g. tests, documentation).

## Acknowledgment

Eclipse CARE is made possible thanks to the following open-source projects:
* **PyGithub** and **python-gitlab**: For interacting with repository hosting platforms.
* **scancode-toolkit-mini** and **typecode-libmagic**: For advanced license and file type detection.
* **colorama**: For providing cross-platform terminal text coloring.
* **hatchling**: For the build system and package management.
* **pytest**: For our testing infrastructure.
* **mkdocs-material**: For generating our project documentation.

## License

This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0, which 
is available at http://www.eclipse.org/legal/epl-2.0.
