Должен ли я прилагать примеры и/или тестовые файлы к моему пакету и где они должны храниться?

Примеры - это вообще хорошая вещь. Особенно, если ваш класс имеет достаточно сложный API. Однако примеры - это только часть документации, но не её замена. Документация и примеры должны находиться в поддиректории 'docs' директории пакета.

Особенно рекомендуется прилагать тестовые скрипты, если ваш класс нужно компилировать, если он требует специфических модулей/программ или ему необходимы дополнительные файлы (например, шаблоны или изображения). Храните их в директории 'tests'.