Add package README

[aidan-casey]

We should add a README for each package and check the package for it in CI.

[Treggats]

@aidan-casey is this part of what we discussed (somewhere)? About the CI checking the composer dependencies.

[aidan-casey]

@Treggats this is less about checking the composer dependencies and more about checking whether each package has a README. We can check that by uncommenting line 52 here, but first we have to write all the README files. 🙂

[Bapawe]

Creating these README files is straightforward, but what essential information should they contain? Is there a recommended template to follow?

[brendt]

I'm not sure. Ideally, each README is carefully hand-crafted for that specific pacakge with a code sample, a quickstart section, and a reference to the docs. I think that would be a good start. Something like this:

The PHP templating engine that speaks your language

composer require tempest/view:1.0-alpha.3

Tempest View is an extension on the most popular templating engine of all time: HTML. Template inheritance and inclusion are modelled via HTML elements; data binding and control structures are handled with attributes.

<x-base title="Home">
    <x-post :foreach="$this->posts as $post">
        {!! $post->title !!}

        <span :if="$this->showDate($post)">
            {{ $post->date }}
        </span>
        <span :else>
            -
        </span>
    </x-post>
    <div :forelse>
        <p>It's quite empty here…</p>
    </div>
    
    <x-footer />
</x-base>

Quickstart

composer require tempest/view:1.0-alpha.3

$container = Tempest::boot(__DIR__);

$view = view(__DIR__ . '/src/b.view.php');

echo $container->get(ViewRenderer::class)->render($view);

Continue reading in the docs

[brendt]

For tempest/view it's pretty simple because I've also made the landing page for it, so I just copied from there. I reckon other components will need some more thought.

[Bapawe]

Thanks, this looks like a great start! I think adding a Contributing section at the end, similar to the README for tempestphp/tempest-framework, would be helpful. It could also increase exposure for your Discord community.

Would you prefer to use composer require tempest/view:1.0-alpha.3 in the README file, or keep it as composer require tempest/view? Using the generic command would avoid the need to update the README with each release.

I'd suggest keeping the example code brief and quickly directing readers to the landing page or/and documentation site.

I'll start working on the README files and will open a PR soon.

[brendt]

I think adding a Contributing section at the end, similar to the README for tempestphp/tempest-framework, would be helpful. It could also increase exposure for your Discord community.

Agree!

Using the generic command would avoid the need to update the README with each release.

Yeah but unfortunately the version without 1.0-alpha.3 won't work correctly for most people. Once we tagged a stable 1.0 release, we should drop it, but for now it's better to keep it in. I'm fine updating it manually, I've been doing that for the docs as well these past two alpha releases :)

I'd suggest keeping the example code brief and quickly directing readers to the landing page or/and documentation site.

Agree!