[thirdparty/libarchive.git] / CONTRIBUTING.md

Thank you for helping us improve libarchive.
The following guidelines will help ensure your contribution gets prompt attention.

# Bugs and other Issues

If you encounter any problems with libarchive,
[please file an issue on our issue tracker](https://github.com/libarchive/libarchive/issues).

All bug reports should include the following information.  You can copy the text below directly into the issue tracker to get started:

```
Basic Information
  Version of libarchive:
  How you obtained it:  (build from source, pre-packaged binary, etc)
  Operating system and version:
  What compiler and/or IDE you are using (include version):

If you are using a pre-packaged binary
  Exact package name and version:
  Repository you obtained it from:

Description of the problem you are seeing:
  What did you do?
  What did you expect to happen?
  What actually happened?
  What log files or error messages were produced?

How the libarchive developers can reproduce your problem:
  What other software was involved?
  What other files were involved?
  How can we obtain any of the above?
```

Depending on the specific type of issue, other information will be helpful:

## Test Failures

If you see any test failures, please include the information above and also:

* Names of the tests that failed.

* Look for the .log files in the /tmp/libarchive_test_*date-and-time* directories.  (On Mac OS, look in $TMPDIR which is different than /tmp.)

Please paste the .log files you will find there directly into your report.


## Problems using libarchive in a program

If you are trying to write a program using libarchive, please include the information above and also:

* It will help us if we can actually run the program.  This is easiest if you can provide source to a short program that illustrates your problem.

* If you have a sufficiently short program that shows the problem, you can either paste it into the report or [put it into a gist](https://gist.github.com).


## Libarchive produced incorrect output

Please tell us what program you ran, any command-line arguments you provided, and details of the input files (`ls -l` output is helpful here).  If the problem involved a command-line program, please copy the full terminal text into the report, including the command line and any error messages.

Please try to make the output file available to us.  Unless it is very large, you can upload it into a fresh github repository and provide a link in your issue report.


## Libarchive could not read a particular input file

Note: If you can provide a **very small** input file that reproduces the problem, we can add that to our test suite.  This will ensure that the bug does not reappear in the future.

A link to the relevant file is usually sufficient.

If you cannot provide the input file or a link to the file, please let us know if there is some other way to obtain it.


## Documentation improvements

We are always interested in improving the libarchive documentation.  Please tell us about any errors you find, including:

* Typos or errors in the manpages provided with libarchive source.

* Mistakes in the [libarchive Wiki](https://github.com/libarchive/libarchive/wiki)

* Problems with the PDF or Wiki files that are automatically generated from the manpages.


# Code Submissions

We welcome all code submissions.  But of course, some code submissions are easier for us to respond to than others. The best code submissions:

* Address a single issue.  There have been many cases where a simple fix to an obvious problem did not get handled for months because the patch that was provided also included an unrelated change affecting an especially complex area of the code.

* Follow existing libarchive code style and conventions.  Libarchive generally follows [BSD KNF](https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9) for formatting code.

* Do not make unnecessary changes to existing whitespace, capitalization, or spelling.

* Include detailed instructions for reproducing the problem you're fixing.  We do try to verify that a submission actually fixes a real problem.  If we can't reproduce the problem, it will take us longer to evaluate the fix.  For this reason, we encourage you to file an issue report first with details on reproducing the problem, then refer to that issue in your pull request.

* Includes a test case.  The libarchive Wiki has [detailed documentation for adding new test cases](https://github.com/libarchive/libarchive/wiki/LibarchiveAddingTest).

* Are provided via Github pull requests.  We welcome patches in almost any format, but github's pull request management makes it significantly easier for us to evaluate and test changes.
Commit	Line	Data
204ad348 TK	1	Thank you for helping us improve libarchive.
	2	The following guidelines will help ensure your contribution gets prompt attention.
	3
	4	# Bugs and other Issues
	5
	6	If you encounter any problems with libarchive,
	7	[please file an issue on our issue tracker](https://github.com/libarchive/libarchive/issues).
	8
	9	All bug reports should include the following information. You can copy the text below directly into the issue tracker to get started:
	10
	11	```
d41eed94 TK	12	Basic Information
	13	Version of libarchive:
	14	How you obtained it: (build from source, pre-packaged binary, etc)
	15	Operating system and version:
	16	What compiler and/or IDE you are using (include version):
	17
	18	If you are using a pre-packaged binary
ff86dd10	19	Exact package name and version:
d41eed94	20	Repository you obtained it from:
204ad348 TK	21
204ad348 TK	22	Description of the problem you are seeing:
d41eed94 TK	23	What did you do?
d41eed94 TK	24	What did you expect to happen?
ff86dd10 TK	25	What actually happened?
ff86dd10 TK	26	What log files or error messages were produced?
204ad348 TK	27
204ad348 TK	28	How the libarchive developers can reproduce your problem:
d41eed94 TK	29	What other software was involved?
	30	What other files were involved?
	31	How can we obtain any of the above?
204ad348 TK	32	```
204ad348 TK	33
ff86dd10 TK	34	Depending on the specific type of issue, other information will be helpful:
ff86dd10 TK	35
204ad348 TK	36	## Test Failures
	37
	38	If you see any test failures, please include the information above and also:
	39
	40	* Names of the tests that failed.
	41
	42	* Look for the .log files in the /tmp/libarchive_test_date-and-time directories. (On Mac OS, look in $TMPDIR which is different than /tmp.)
	43
	44	Please paste the .log files you will find there directly into your report.
204ad348	45
d41eed94	46
204ad348 TK	47	## Problems using libarchive in a program
	48
	49	If you are trying to write a program using libarchive, please include the information above and also:
	50
d41eed94 TK	51	* It will help us if we can actually run the program. This is easiest if you can provide source to a short program that illustrates your problem.
	52
	53	* If you have a sufficiently short program that shows the problem, you can either paste it into the report or [put it into a gist](https://gist.github.com).
204ad348	54
204ad348 TK	55
	56	## Libarchive produced incorrect output
	57
ff86dd10 TK	58	Please tell us what program you ran, any command-line arguments you provided, and details of the input files (`ls -l` output is helpful here). If the problem involved a command-line program, please copy the full terminal text into the report, including the command line and any error messages.
ff86dd10 TK	59
d41eed94 TK	60	Please try to make the output file available to us. Unless it is very large, you can upload it into a fresh github repository and provide a link in your issue report.
d41eed94 TK	61
204ad348	62
ff86dd10	63	## Libarchive could not read a particular input file
204ad348	64
d41eed94 TK	65	Note: If you can provide a very small input file that reproduces the problem, we can add that to our test suite. This will ensure that the bug does not reappear in the future.
d41eed94 TK	66
ff86dd10 TK	67	A link to the relevant file is usually sufficient.
	68
	69	If you cannot provide the input file or a link to the file, please let us know if there is some other way to obtain it.
204ad348	70
204ad348	71
d41eed94 TK	72	## Documentation improvements
	73
	74	We are always interested in improving the libarchive documentation. Please tell us about any errors you find, including:
	75
	76	* Typos or errors in the manpages provided with libarchive source.
	77
	78	* Mistakes in the [libarchive Wiki](https://github.com/libarchive/libarchive/wiki)
	79
	80	* Problems with the PDF or Wiki files that are automatically generated from the manpages.
204ad348 TK	81
	82
	83	# Code Submissions
	84
	85	We welcome all code submissions. But of course, some code submissions are easier for us to respond to than others. The best code submissions:
	86
ff86dd10	87	* Address a single issue. There have been many cases where a simple fix to an obvious problem did not get handled for months because the patch that was provided also included an unrelated change affecting an especially complex area of the code.
d41eed94 TK	88
	89	* Follow existing libarchive code style and conventions. Libarchive generally follows [BSD KNF](https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9) for formatting code.
	90
ff86dd10	91	* Do not make unnecessary changes to existing whitespace, capitalization, or spelling.
204ad348 TK	92
	93	* Include detailed instructions for reproducing the problem you're fixing. We do try to verify that a submission actually fixes a real problem. If we can't reproduce the problem, it will take us longer to evaluate the fix. For this reason, we encourage you to file an issue report first with details on reproducing the problem, then refer to that issue in your pull request.
	94
	95	* Includes a test case. The libarchive Wiki has [detailed documentation for adding new test cases](https://github.com/libarchive/libarchive/wiki/LibarchiveAddingTest).
	96
	97	* Are provided via Github pull requests. We welcome patches in almost any format, but github's pull request management makes it significantly easier for us to evaluate and test changes.
	98