WIP: Add CONTRIBUTING.md and explain version increment

[nikhiljnv]

Add CONTRIBUTING.md to explain

1. How to contribute to OpenCL ICD Loader project.
2. ICD loader versioning guidelines including
   when to increment the version number.

[CLAassistant]

All committers have signed the CLA.

[bashbaug]

Is there a reason why we wouldn't want to update the Linux library version when making pull requests?

If we don't update the Linux library version then a) how can we ensure a newer ICD loader with a critical bugfix will overwrite an older ICD loader without the bugfix, or conversely b) how can we ensure that an older ICD loader will not overwrite a newer ICD loader?

[kepatil]

We probably should increment version for Linux too. However, Linux does not seem to have an exact equivalent of Windows FileVersion embedded inside the library file.

Instead I see a filename versioning convention based on symlinks, like libfoo.MAJOR -> libfoo.MAJOR.MINOR -> libfoo.MAJOR.MINOR.RELEASE. We could perhaps increment RELEASE with each change.

However, I don't know of an authoritative reference for this scheme. Also, I don't know how to achieve this using CMake. Any pointers would be helpful.

[bashbaug]

This sounds reasonable.

We have this in our CMake file today:

set_target_properties (OpenCL PROPERTIES VERSION "1.2" SOVERSION "1")

The VERSION line controls which symlinks are created. With our current CMake file we get:

$ ls -l libOpenCL.so*
lrwxrwxrwx 1 bashbaug bashbaug    14 Jul 22 16:48 libOpenCL.so -> libOpenCL.so.1
lrwxrwxrwx 1 bashbaug bashbaug    16 Jul 22 16:48 libOpenCL.so.1 -> libOpenCL.so.1.2
-rwxrwxr-x 1 bashbaug bashbaug 44784 Jul 22 16:48 libOpenCL.so.1.2

We can add a "release" version and it will give us:

$ ls -l libOpenCL.so*
lrwxrwxrwx 1 bashbaug bashbaug    14 Jul 22 16:46 libOpenCL.so -> libOpenCL.so.1
lrwxrwxrwx 1 bashbaug bashbaug    18 Jul 22 16:46 libOpenCL.so.1 -> libOpenCL.so.1.2.0
-rwxrwxr-x 1 bashbaug bashbaug 44784 Jul 22 16:46 libOpenCL.so.1.2.0

Note that the "soversion" is different and gets embedded into the file itself:

$ objdump -p libOpenCL.so.1.2 | grep SONAME
  SONAME               libOpenCL.so.1

If we set the CMake project version we could probably use that, both for Windows and Linux, so we'd only need to change the version in one place:

https://cmake.org/cmake/help/latest/command/project.html

I suspect there's a way to generate a new patch version for each git commit but I haven't found a way to do that just yet.

[bashbaug]

I think the updated text is a step in the right direction, but I think the documentation should describe what our convention is, and not what it should be:

ICD loader library version should take the form MAJOR.MINOR.RELEASE...

If we think our convention should be different than what we are doing right now (say, that it should include a RELEASE version) then let's fix it.

[nikhiljnv]

Updated the document with linux versioning suggested above.