Contributing

The Core ML .mlmodel file format is a publicly documented specification. The Core ML Tools source code is 100% open source under the BSD license.

As the Core ML open source community, we welcome all contributions and ideas to grow the product. We ask that you follow the contributing guidelines and code of conduct](https://github.com/apple/coremltools/blob/master/CONTRIBUTING.md, which are typical of open source communities. See Contribution Guidelines.

You can contribute in the following ways:

• Issues and queries: Tell us about an issue, request a feature or enhancement, or ask a question.

• Documentation: Help us improve the documentation.

• Contributions: Add new code to improve a feature or add functionality.

Source code

For the source code, see the coremltools GitHub repository.

Issues and queries

We encourage you to resolve or add comments to any open issue in the repository.

Use these templates to tell us about a bug or issue, request a feature or enhancement, or ask a question. Fill in the template as much as possible to help others in the community understand what you are saying, so that they can promptly respond. If applicable, provide the model you used when logging an issue, and any code or scripts to reproduce the issue.

If you find a software issue, follow these steps:

1. Enter the following pip command to ensure that you are using the newest version of the coremltools package:

   pip install coremltools --upgrade
   

   Install/upgrade instructions

   For instructions on installing or upgrading Core ML Tools, see Installing Core ML Tools.

2. Check currently open pull requests in the repository to see if the issue is already being addressed.

3. Check open issues to see if the issue has already been reported. Use the Label dropdown menu to filter issues by a label such as bug. If an issue already exists, add a comment or thumbs-up to indicate that the others are having the same problem.

4. Try to reproduce the problem, copy any results or errors, and paste them into your issue report.

5. Provide useful information about your configuration, such as the OS version, coremltools version, and so on. The template walks you through this process.

Security issue

An ideal issue report includes a script to completely reproduce the issue along with models, sample code, or data required for the script. If you are not comfortable sharing this publicly, please file a report with developer.apple.com.

Once you submit an issue, feature request, or question, members of the community will review it. The Core ML team will determine how to proceed with it, and add the appropriate labels to it.

Documentation

Help us improve the documentation. Even if you find only a typo, don’t hesitate to report it. To make changes, send a pull request as described in Contributions and add the docs label to it (see Labels for details).

Contributions

Add new functionality to the Core ML Tools repository by submitting a GitHub pull request.

• For an example, see this pull request for enhancing the quantization utility.

• To see pull requests still in progress, see the list of current pull requests.

• For instructions on forking the repository and creating pull requests, see GitHub Standard Fork & Pull Request Workflow.

Before contributing code, be sure to install the source code properly and test your code. For details, see Building from Source.

Once you submit a pull request, members of the community will review it. The Core ML team will determine how to proceed with it, and add the appropriate labels to it. A pull request must be approved by a Core ML team member.

Labels

Core ML team members will add labels to your issues, requests, questions, or pull requests. For a description of each label, see the labels page in the repository. An issue typically has the following types of labels:

• Status label (turquoise in color): The issue’s stage in the process. Status labels include:

  • triaged: Team members have reviewed and examined the issue and assigned a release (if applicable). The issue may still be awaiting a response or investigation, or may need discussion.

  • awaiting response: The issue needs a response from the issue’s author.

  • duplicate: The issue is a duplicate. Progress will appear on a similar previously-logged issue.

  • repro needed: Team members need more information to reproduce the issue.

  • investigation: Team members are investigating the issue.

• Type of issue (red in color):

  • bug: Unexpected behavior that should be fixed. Use this label with issues you create using the bug template.

  • docs: Errors or accuracy issues in the documentation, including requests for clarification and additional information.

  • enhancement: An improvement to an existing feature.

  • feature request: Functionality that doesn’t currently exist. Use this label with issues you create using the feature request template.

  • question: Question to the team, such as a request for clarification. Use this label with issues you create using the question template.

• Framework label (orange in color): Use this label to specify the framework that this issue is appearing in. Examples include caffe, onnx, pytorch, tf1.x (TensorFlow 1), and tf2.x / tf.keras (TensorFlow 2 and TensorFlow Keras).

• Issues for contributors to complete: If an issue is good for a contributor to self-assign, it may include the good first issue label.