Merge pull request #5 from IBM/4-finish-the-documentation

4 finish the documentation

Author: PiotrAniola82

CONTRIBUTING.md

@@ -2,10 +2,10 @@
 Our project welcomes external contributions. If you have an itch, please feel
 free to scratch it.
 
-To contribute code or documentation, please submit a **FIXME** [pull request](https://github.com/ibm/javacore-analyse/pulls).
+To contribute code or documentation, please submit a [pull request](https://github.com/IBM/javacore-analyser/compare).
 
 A good way to familiarize yourself with the codebase and contribution process is
-to look for and tackle low-hanging fruit in the **FIXME** [issue tracker](https://github.com/ibm/javacore-analyse/issues).
+to look for and tackle low-hanging fruit in the [issue tracker](https://github.com/ibm/javacore-analyser/issues).
 Before embarking on a more ambitious contribution, please quickly [get in touch](#communication) with us.
 
 **Note: We appreciate your effort, and want to avoid a situation where a contribution
@@ -14,15 +14,16 @@ cannot be accepted at all!**
 
 ### Proposing new features
 
-If you would like to implement a new feature, please **FIXME** [raise an issue](https://github.com/ibm/javacore-analyse/issues)
+If you would like to implement a new feature, please 
+[raise an issue](https://github.com/IBM/javacore-analyser/issues/new)
 before sending a pull request so the feature can be discussed. This is to avoid
 you wasting your valuable time working on a feature that the project developers
 are not interested in accepting into the code base.
 
 ### Fixing bugs
 
-If you would like to fix a bug, please **FIXME** [raise an issue](https://github.com/ibm/javacore-analyse/issues) before sending a
-pull request so it can be tracked.
+If you would like to fix a bug, please [raise an issue](https://github.com/IBM/javacore-analyser/issues/new) before 
+sending a pull request so it can be tracked.
 
 ### Merge approval
 
@@ -72,13 +73,23 @@ git commit -s
 Please feel free to connect with us on our [Slack channel](https://ibm.enterprise.slack.com/archives/C01KQ4X0ZK6).
 
 ## Setup
-**FIXME** Please add any special setup instructions for your project to help the developer
-become productive quickly.
+1. Install Pycharm
+2. Navigate to **Project from Version Control...** and follow next steps
+
+To run the tool with sample data perform the following steps:
+1. Right click on **javacore_analyzer.py** directory in **Project** view and select **Modify Run Configuration...**. 
+When the window appears, add the following commandline to **run parameters**  
+`test/data/javacores /tmp/javacoreanalyser_output`  
+Change the second parameter to the directory where you want the output report be created.
+2. Right click again on **javacore_analyzer.py** and select **Run** or **Debug**.
 
 ## Testing
-**FIXME** Please provide information that helps the developer test any changes they make
-before submitting.
+As default the tests in Pycharm are ran in the current selected directory. However we want to run them in main 
+directory of the tool (**javacore-analyser** directory, not **test** directory). 
+1. Right click on **test** directory in **Project** view and select **Modify Run Configuration...**. 
+When the window appears, the **Working Directory** will be set to **test** directory. 
+Change it to **javacore-analyser** directory
+2. Right click again on **test** and select **Run** or **Debug**.
 
 ## Coding style guidelines
-**FIXME** Optional, but recommended: please share any specific style guidelines you might
-have for your project.
+We use [PEP 8](https://peps.python.org/pep-0008/) Python style for Python files.

MAINTAINERS.md

@@ -1,5 +1,5 @@
 # MAINTAINERS
 
-- Krzysztof Kazmierczyk <[email protected]>
-- Piotr Aniola <[email protected]>
-- Tadeusz Janasiewicz <[email protected]>
+* Krzysztof Kazmierczyk <[email protected]>
+* Piotr Aniola <[email protected]>
+* Tadeusz Janasiewicz <[email protected]>

README.md

@@ -7,32 +7,43 @@
 <!-- Not always needed, but a scope helps the user understand in a short sentance like below, why this repo exists -->
 ## Scope
 
-The tool analyzes Javacores and verbose gc logs and provides some reports like cpu/gc usage, blocked threads, some tips regarding the javacores
-<!-- A more detailed Usage or detailed explaination of the repository here -->
-## Usage
-
-This repository contains some example best practices for open source repositories:
+The tool analyzes Javacores and verbose gc logs and provides some reports like cpu/gc usage, blocked threads, some tips regarding the javacores. The tool can process the following data:
+* Set of Javacores from the same run. Optionally you can add verbose.gc log file
+* Single Javacore
 
-* [LICENSE](LICENSE)
-* [README.md](README.md)
-* [CONTRIBUTING.md](CONTRIBUTING.md)
-* [MAINTAINERS.md](MAINTAINERS.md)
-<!-- A Changelog allows you to track major changes and things that happen, https://github.com/github-changelog-generator/github-changelog-generator can help automate the process -->
-* [CHANGELOG.md](CHANGELOG.md)
-* [REQUIREMENTS.md](REQUIREMENTS.md)
+  
+<!-- A more detailed Usage or detailed explaination of the repository here -->
+## Installation and usage
+
+### Installation:
+The tool requires Python 3.9 or higher plus some packages - see more in [REQUIREMENTS](REQUIREMENTS.md). Despite it is not mandatory, it is recommended in Python to use virtual environment to manage packages.
+
+Steps:
+1. Download and install Python. Usually the latest version is supported. Search for supported versions in 
+[REQUIREMENTS](REQUIREMENTS.md)
+2. Download and unpack the tool.
+3. Create and activate Virtual Environment according to [Creating virtual environments](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments).
+4. Install all required pip packages. Navigate in command line to unpacked tool and type
+   `pip install -r requirements.txt`
+
+### Running the tool:
+1. Activate your created virtual environment according to activate Virtual Environment according to [Creating virtual environments](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments)
+2. Navigate in command line to unpacked tool and run the following command:  
+  `python javacore_analyzer.py <input-data> <output-dir>`  
+Where `<input-data>` is one of the following:
+* The directory containing javacores and optionally verbose gc
+* Archive (7z, zip, tar.gz, tar.bz2) containint the same
+* List of the javacores separated by `'` character. Optionally you can add `--separator` option to define your own separator.
+You can type the following command to obtain the help:  
+`python javacore_analyzer.py --help`
 
-<!--
-> These are optional
--->
 
 <!-- The following are OPTIONAL, but strongly suggested to have in your repository. -->
 <!--
 * [dco.yml](.github/dco.yml) - This enables DCO bot for you, please take a look https://github.com/probot/dco for more details.
 * [travis.yml](.travis.yml) - This is a example `.travis.yml`, please take a look https://docs.travis-ci.com/user/tutorial/ for more details.
 -->
 
-These may be copied into a new or existing project to make it easier for developers not on a project team to collaborate.
-
 <!-- A notes section is useful for anything that isn't covered in the Usage or Scope. Like what we have below. -->
 ## Notes
 
@@ -72,8 +83,19 @@ If you would like to see the detailed LICENSE click [here](LICENSE).
 ```
 ## Authors
 
-- Krzysztof Kazmierczyk <[email protected]>
-- Piotr Aniola <[email protected]>
-- Tadeusz Janasiewicz <[email protected]>
+* Krzysztof Kazmierczyk <[email protected]>
+* Piotr Aniola <[email protected]>
+* Tadeusz Janasiewicz <[email protected]>
 
 [issues]: https://github.com/IBM/javacore-analyser/issues/new
+
+## Another pages
+
+Another useful pages:
+* [LICENSE](LICENSE)
+* [README.md](README.md)
+* [CONTRIBUTING.md](CONTRIBUTING.md)
+* [MAINTAINERS.md](MAINTAINERS.md)
+<!-- A Changelog allows you to track major changes and things that happen, https://github.com/github-changelog-generator/github-changelog-generator can help automate the process -->
+* [CHANGELOG.md](CHANGELOG.md)
+* [REQUIREMENTS.md](REQUIREMENTS.md)

REQUIREMENTS.md

@@ -1,5 +1,5 @@
 ### System Requirements
 
-1. Python 3.8 or newer
+1. Python 3.9 or newer
 2. Modules installed from **requirements.txt** file. You can install them using 
 `pip install -r requirements.txt` command.