update docs (#405)

BREAKING-CHANGES.md

@@ -18,7 +18,7 @@ To exit with return code 1 even if only WARN-level breaking changes are found, a
 
 ### Output Formats
 The default output format is human-readable text.  
-You can specify the `--format` flag to output breaking-changes in json or yaml.
+You can specify the `--format` flag to output breaking-changes in json, yaml, githubactions or junit formats.
 
 ### API Stability Levels
 When a new API is introduced, you may want to allow developers to change its behavior without triggering a breaking-change error.  
@@ -67,23 +67,23 @@ In most cases the `x-extensible-enum` is similar to enum values, except it allow
 If you don't use the `x-extensible-enum` in your OpenAPI specifications, nothing changes for you, but if you do, oasdiff will identify breaking changes related to `x-extensible-enum` parameters and properties.
 
 ### Optional Breaking-Changes Checks
-You can use the `--include-checks` flag to include the following optional checks:
-- response-non-success-status-removed
-- api-operation-id-removed
-- api-tag-removed
-- api-schema-removed
-- response-property-enum-value-removed
-- response-mediatype-enum-value-removed
-- request-body-enum-value-removed
+You can use the `--include-checks` flag to include optional checks for breaking-changes.  
+Use the `oasdiff checks --required false` command to see the list of optional checks.  
 
 For example:
 ```
 oasdiff breaking data/openapi-test1.yaml data/openapi-test3.yaml --include-checks response-non-success-status-removed
 ```
 
+### Localization
+To display changes in other languages use the `--lang` flag.  
+Currently English and Russian are supported.  
+[Please improve oasdiff by adding your own language](https://github.com/Tufin/oasdiff/issues/383).
+
 ### Customizing Breaking-Changes Checks
-If you encounter a change that isn't considered breaking by oasdiff and you would like to consider it as a breaking-change you may add an [optional breaking-changes check](#optional-breaking-changes-checks).  
-For more information, see [this guide](CUSTOMIZING-CHECKS.md) and this example of adding a custom check: https://github.com/Tufin/oasdiff/pull/208/files
+If you encounter a change that isn't considered breaking by oasdiff you may:
+1. Check if the change is already available as an [optional breaking-changes check](#optional-breaking-changes-checks).  
+2. Add a [custom check](CUSTOMIZING-CHECKS.md)
 
 ### Examples
 [Here are some examples of breaking and non-breaking changes that oasdiff supports](BREAKING-CHANGES-EXAMPLES.md).  

CHANGELOG.md

@@ -0,0 +1,23 @@
+## Changelog
+As your API evolves, it will undergo changes. Some of these changes may be "breaking" while others are not.  
+The changelog provides a list of all significant changes between two versions of the OpenAPI specification, including non-breaking changes.
+
+To generate the changelog between two specs run oasdiff with the `changelog` command:
+```
+oasdiff changelog https://raw.githubusercontent.com/Tufin/oasdiff/main/data/openapi-test1.yaml https://raw.githubusercontent.com/Tufin/oasdiff/main/data/openapi-test3.yaml
+```
+
+The changes are categorized into three levels:
+- `INFO` - Changes which are not breaking yet still important to know about
+- `WARN` - Warnings are potential breaking changes which developers should be aware of, but cannot be confirmed programmatically
+- `ERR` - Errors are definite breaking changes which should be avoided
+
+The changelog is actually an extension of the breaking changes output with additional `INFO`-level changes.  
+See [the breaking-changes documentation](BREAKING-CHANGES.md) for additional options that can be also be used with changelog command.
+
+### Output Formats
+The default changelog format is human-readable text.  
+You can specify the `--format` flag to output the changelog as json or yaml.
+
+### Customizing the Changelog
+If you encounter a change that isn't logged by oasdiff you may add a [custom check](CUSTOMIZING-CHECKS.md).

CUSTOMIZING-CHECKS.md

@@ -26,3 +26,6 @@
 3. Make sure that [BREAKING-CHANGES-EXAMPLES.md](BREAKING-CHANGES-EXAMPLES.md) was updated with your use-cases
 4. If your check is optional, also add it to [this list of optional checks](https://github.com/Tufin/oasdiff#optional-breaking-changes-checks)
 
+## Example
+See this example of adding a custom check: https://github.com/Tufin/oasdiff/pull/208/files
+

README.md

@@ -19,8 +19,8 @@ docker run --rm -t tufin/oasdiff changelog https://raw.githubusercontent.com/Tuf
 
 ## Features 
 - Detect [breaking changes](BREAKING-CHANGES.md)
+- Display a user-friendly [changelog](CHANGELOG.md) of all important API changes
 - OpenAPI diff in YAML, JSON, Text/Markdown or HTML
-- Display a user-friendly [changelog](#openapi-changelog) of all important API changes
 - [Run from Docker](#openapi-diff-with-docker)
 - [Embed in your go program](#embedding-oasdiff-into-your-program)
 - OpenAPI diff of local files system or remote files over http/s