Added initial contributing documentation

- Added a CODE_OF_CONDUCT.md
- Modified CONTRIBUTING.md with more details
- Modified the README.md to reference the new information

Signed-off-by: Nisha K <[email protected]>

Author: Nisha K

CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by sending an email to [email protected] and/or [email protected]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+

CONTRIBUTING.md

@@ -1,18 +1,104 @@
-### Give me your bugs, your docs, your pull requests...
+### Contributing to the Tern project
 
-But before you do, please take a moment to read the code of conduct
+Once again, we hope you have read our [code of conduct](/CODE_OF_CONDUCT.md) before starting.
 
-### How to file a bug
+We are excited to be working with the community to help with Open Source compliance obligations!
 
-### How to submit new or corrected documentation
+You can contribute in the following ways:
 
-### How to submit a pull request
+* Improving the Documentation
+* Adding to the Command Library
+* Improving the Unit and Functional Tests
+* Improving the Core Project
 
-### Adding to the Command Library
+### Skills for contributing
 
-Link to command library wiki
+* English (not necessarily fluent but workable)
+* Python (a working knowledge of object oriented Python would be nice, but if you know how python functions/modules work, this is enough to get you started)
+* YAML (Tern uses yaml files heavily for data lookup. An overview of YAML can be found [here](http://yaml.org/)
 
-### Talk to me!
+### Keeping in touch
 
-### Glossary
+If you would like to ask a question or start a discussion with the maintainers, post a topic on the [public forum](https://groups.google.com/forum/#!forum/tern-maintainers). No registration is required. We will respond to your question or topic within three days unless the post was over the weekend in which case we may take longer to respond. This is our primary communication channel so it is highly likely that you will get a response here.
 
+If you would like to chat live, you can join the [slack channel](https://vmwarecode.slack.com/messages/tern). If you don't have an @vmware.com or @emc.com email, please sign up at https://code.vmware.com/slack to get a Slack invite. Although we monitor the channel, we may not respond right away and if the same question was asked on the forum, we will choose to respond there.
+
+### An overview of the contribution lifecycle
+
+Once you decide that you would like to play around with the project
+
+1. Fork the git repository to your personal github account. See [here](https://help.github.com/articles/fork-a-repo/#fork-an-example-repository) and [here](https://help.github.com/articles/fork-a-repo/#keep-your-fork-synced) to get you started.
+2. Create a branch for your work
+```
+$ git checkout -b my-work
+```
+3. Work on the code
+4. Update your branch with the latest from upstream. See [here](https://help.github.com/articles/syncing-a-fork/) for an example. Note that if you have not worked on the master branch of your fork, the merges should be fast-forward merges and you should not be resolving conflicts.
+5. Replay your work on top of the latest
+```
+$ git checkout my-work
+$ git rebase master
+```
+Expect to spend time resolving conflicts here.
+6. Run functional tests.
+6. Push your branch changes to a remote branch in your fork of the repo
+7. Submit a pull request (PR for short) to the upstream repo. See [here](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) to get you started. If all goes well, there should be no conflicts.
+8. A reviewer will further communicate with you through the PR.
+9. If everything looks good the PR will be accepted.
+
+### Commit message format
+
+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 a summary taken from [this blog](https://chris.beams.io/posts/git-commit/)
+
+* 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
+```
+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
+```
+### Filing an Issue
+
+You may file an issue through the github issue tracker. Please follow the same guidelines as the commit message guidelines when formatting your issue. Please make sure to include the following for quick debugging and resolution:
+
+* The SHA256 commit at which the bug occured
+* The project release version
+* Your dev environment
+* Reproduction steps
+* The contents of tern.log (which may not have everything that went to stdout so the contents of that would also be helpful if it is different)
+
+You may file an issue and create a pull request that references said issue. This, however, does not guarantee acceptance of the PR. Contributing in this way works for small bug or documentation fixes but doesn't lend itself well to large updates. We encourage you to start a discussion on the forum. Typically a follow up issue will be created referencing the topic.
+
+### Troubleshooting
+
+* Tern produces a generic message about being unable to execute a docker command with a CalledProcessError from the get go: Make sure the docker daemon is running first
+* Unable to find module 'yaml': make sure to activate the python virtualenv first and then run pip install -r requirements.txt 

README.md

@@ -1,46 +1,53 @@
-### What is Tern?
+### Welcome to the Tern Project
 
 Tern is a tool to find the metadata for packages installed in Docker containers, specifically the sources, versions and licenses. It does this by looking up
-a "command library" for code snippets to execute in a running container. The command library is a list of shell commands used to install and remove packages
-with associated shell commands to run within the container to retrieve specific information.
+a "command library" for code snippets to execute in a running container. The command library is a list of commands used to install and remove packages
+(such as a package manager) with associated shell commands to run within the container to retrieve specific information.
 
-Tern was created to address the issue that Docker containers where distributed without certainity of what packages they contained. This becomes especially problematic when distributing packages with incompatible licenses or licenses that have restrictions on distribution.
+Tern was created to help developers meet open source compliance requirements for containers. Tools like Docker make it easy to build and distribute containers but keeping track of what is installed is left to developer or devops teams. Tern aims to bridge this gap.
 
-### Requirements
+### Try it out
+
+#### Requirements
 - Git (Installation instructions can be found here: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
 - Docker CE (Installation instructions can be found here: https://docs.docker.com/engine/installation/#server)
 - Python 3.6.2 (sudo apt-get install python3.6 or sudo dnf install python36)
 
-### Getting Started
-Once you have installed the requirements you can run these commands in a terminal to get you started:
+Make sure the docker daemon is running. If it is you can run these commands to get you started:
 ```
 $ python3 -m venv ternenv
 $ cd ternenv
-$ git clone git@gitlab.eng.vmware.com:opensource/tern.git
+$ git clone git@github.com:vmware/tern.git
 $ source bin/activate
 $ cd tern
 $ pip install -r requirements.txt
-$ ./tern report -d samples/debian_vim/Dockerfile
+$ ./tern report -d samples/photon_git/Dockerfile
 ```
-If you come across any issues, please file a bug with the complete output. If it completes successfully, take a look at report.txt. You can file bugs against the report as well
+Take a look at report.txt to see what packages are installed in the created Docker image and how Tern got this information. Feel free to try this out on the other sample Dockerfiles in the samples directory or on Dockerfiles you may be working with.
 
-### Usage
+#### To get a summary report
 ```
-$ python3 -m venv ternenv
-$ cd ternenv
-$ git clone [email protected]:opensource/tern.git
-$ source bin/activate
-$ cd tern
-$ pip install -r requirements.txt
-$ ./tern -h
+$ ./tern report -s -d samples/photon_git_Dockerfile
 ```
+WARNING: Tern is meant to give guidance on what may be installed for each line in a Dockerfile so it is recommended that for the purpose of investigation, the default report is used. The summary report may be used as the output of a build artifact or something to submit to a compliance or legal team.
 
-### To run a test
+#### To run a test
 ```
 $ cd ternenv
 $ source bin/activate
 $ git clone [email protected]:opensource/tern.git
 $ cd tern
 $ export PYTHONPATH=`pwd`
 $ python tests/<test file>.py
+
 ```
+### Documentation
+Architecture, function blocks and code descriptions are located on the Wiki. Feel free to use it as a guide to usage and development. We also welcome contributions to the documentation. See the [contributing guide](/CONTRIBUTING.md) to find out how to submit changes.
+
+### Get Involved
+
+Do you have questions about Tern? Do you think it can do better? Would you like to make it better? You can get involved by giving your feedback and contributing to the code, documentation and conversation!
+
+Please read our [code of conduct](/CODE_OF_CONDUCT.md) first.
+
+Next, take a look at the [contributing guide](/CONTRIBUTING.md) to find out how you can start.