Once again, we hope you have read our code of conduct before starting.
We are excited to work with anyone at any level contributing their time and effort towards the project.
You can contribute in the following ways:
Start a Discussion
- Ask questions about the project goals, features, a specific use case, or clarification on documentation. Asking questions lead to issues being filed, eventually making the project more usable.
File Issues
- Run the code against any Docker image you are using, or any of the tests and submit bug reports when you find them.
Contribute Documentation
- Improve the documentation, project structure and workflow by creating a proposal.
- Contribute changes to documentation by submitting pull requests to it.
Contribute Code
- Resolve Issues
- Improve the robustness of the project by:
The short answer is 'yes'!
The long answer is that there are some basic requirements that will help you contribute to any project on GitHub and this one in particular. Leveling up requires some extra knowledge:
Beginner
- English (not necessarily fluent but workable)
- The Python 3 Programming Language (Python is a very friendly community with plenty of tutorials you can search for)
- The Git version control system. Follow GitHub's setup guide here. You can also practice submitting a pull request with no code here.
Intermediate
- YAML (Tern uses yaml files heavily for data lookup. An overview of YAML can be found here)
- Object Oriented Programming in Python
- Python virtual environments
- Unix Command Line and shell scripts
- Linux System Administration
- Docker Containers
- Vagrant
Advanced
- Container Images
- OverlayFS
- Advanced Python knowledge
- Linux Kernel knowledge would be nice
The fastest way you can get our attention is by filing an issue. We have some templates that help with organizing the information but if you don't think any of them are suitable, just file a regular GitHub issue. All issue templates are located in the .github/ISSUE_TEMPLATE folder in your local clone if you want to take a look at it before filing an issue.
You can:
- Ask a question
- Submit a proposal
- Submit a feature request
- File a bug report
- File a regular GitHub issue
Please do not submit a pull request without filing an issue. We will ask you to file one and refer to it in your commit message before we merge it.
A note about maintainer's time Maintainers are people with lives of their own. The typical time to get a response to a question or a review on a PR is 3 business days but we take chunks of time off for other things as well so it could take longer.
Project Maintainers
- @nishakm
- @rnjudge
You can post a topic on the public forum. You will need to apply to join the group before posting.
If you would like to chat live, you can join the Slack channel. If you don't have an @vmware.com or @emc.com email, please follow this link, enter your email address and click "Request Invite". If you are already a member of the slack channel, or if you have an @vmware.com or @emc.com email, you can simply sign-in to the Slack channel.
Look for issues without the label assigned on it. This indicates that someone is already working on it. Some labels that may be of interest are listed here:
- docs: Documentation changes
- good-first-issue: A good issue to start off with if this is your first time contributing to this project
- first-timers-only: A good issue to start off with if this is your first time contributing to any GitHub project
- tests: An issue regarding testing the project code
- tools: An issue regarding tools for developers or contributors
- bug: A bug in code functionality
- arch: An issue requiring some architectural change
To start, comment on the issue asking if you can work on it. A maintainer will tag your username to the issue and apply the assigned label on it.
For hassle-free code contribution, follow the steps below. NOTE: I mostly work in a Linux environment using a basic text editor (vim). Your set-up could be different. If it is, please feel free to submit an issue regarding your development environment and a pull request to add to this documentation.
You may have already cloned the project and started working on it. If you're reading this after the fact, I would highly recommend you save your work and set up a new development environment in this way.
- Set up a Python virtual environment that has either the Python 3.6 or Python 3.7 executable. See here for instructions on how to set this up using your host machine's Python3. There are also a guide to managing virtual environments using pipenv but I haven't used it. Once done, you should have a folder created. Change to that folder.
- Clone your fork of Tern in the virtual environment folder.
- Activate your virtual environment
source bin/activate. NOTE: This specific activate script only works for Bash shells. If you need to activate a Fish Shell or C Shell you should usesource/bin/activate.fishorsource/bin/activate.csh, respectively. - Change directory into the clone.
- Run
pip install wheel. This is needed because some dependencies for development fail to build python wheels. - Run
pip install -e.[dev]. This will install tern in development mode. This will install the project dependencies and Prospector which is a tool to check for style and linting errors. - Highly recommended: If you want to set up your project for long-term open source contribution, I highly suggest following this setup.
- Install VirtualBox and Vagrant for Mac or Windows
- Run
git clone https://github.com/tern-tools/tern.git - Run
cd tern/vagrant - Run
vagrant up - Run
vagrant ssh - Run
python3 -m venv ternenv - Run
cd ternenv - Run
source bin/activate - Run
cp -r /tern . - Run
cd tern - Run
pip3 install wheel - Run
pip3 install -e.[dev]This will install tern at the tip of master on Windows and Mac.
- Install your changes in the development virtual environment
pip3 install -e.[dev] - Run prospector from the project's root directory
prospector . - Fix any issues prospector brings up.
- Run bandit from the project's root directory
bandit -r . - Fix any issues bandit brings up.
- Test your changes.
After you make the changes just run tox. This will run a set tests and inform you if anything is wrong.
To learn more about how Tern can be used with external tools as extensions, see these instructions.
Tern will be able to find the absolute path of the command line tool which will be used as an extension if it is available on the system. For instance, to make Tern work with Scancode, you can install Scancode in your development environment such that it is available when you run which scancode.
Note that you do not need to do this if you are using a Python library as an extension.
If you are developing on Tern and Scancode together, you will need to install both packages in your python virtual environment before running Tern. Eg:
$ python3 -m venv devenv
$ cd devenv
$ git clone [email protected]:tern-tools/tern.git
$ git clone [email protected]:nexB/scancode-toolkit.git
$ cd tern
$ pip install -e.[dev] .
$ cd ../scancode-toolkit
$ pip install .
$ cd ..
$ tern report -x scancode -i debian:buster
Tern follows general PEP8 style guidelines. Apart from that, these specific rules apply:
- Indents for .py files are 4 spaces long
- Indents for .yml files are 2 spaces long
- Modules are listed as external dependencies, followed by a space, followed by internal dependencies, listed individually and in alphabetical order. For example:
# external dependencies not part of Tern
# possibly part of the python package or installed via pip
import os
import sys
# internal dependencies that are part of Tern
import common
from utils import rootfs
- Minimize cyclomatic complexity. Most python style checkers also come with McCabe complexity checkers. A good rule of thumb is to limit the number of if-then-else statements to 3 and return once in a module.
The commit message of your PR should be able to communicate what problem/opportunity the PR addresses without any reference to forum messages or discussions on slack or IRL. You may make a reference to a github issue number using the github format (eg: Resolves: #1). Here is an overview of what is needed in a good commit message taken from this blog
- Separate subject from body with a blank line
- Limit the subject line to 50 characters
- Capitalize the subject line
- Do not end the subject line with a period
- Use the imperative mood in the subject line
- Wrap the body at 72 characters
- Use the body to explain what and why vs. how
In addition to this, we would like you to sign off on your commit. You can configure git to automatically do this for you when you run 'git commit -s'.
$ git config --global user.name "Some Dev"
$ git config --global user.email [email protected]
You should see a footer in your commit message like this:
Signed-off-by: Some Dev <[email protected]>
Please use a name you would like to be identified with and an email address that you monitor.
Example:
Summarize changes in around 50 characters or less
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
Resolves: #123
See also: #456, #789
Signed-off-by: Some Dev <[email protected]>
- Unable to find module 'yaml': make sure to activate the python virtualenv first and then run
pip install . - Cannot find bdist_wheel: This usually happens when there is a mismatch between the python version and the virtualenv version. Make sure the symlinks you are using point to the right versions in
/usr/bin/python.