Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCS Module standard 1.0 #4632

Closed
wants to merge 1 commit into from

Conversation

Projects
None yet
6 participants
@camfindlay
Copy link
Contributor

commented Sep 28, 2015

First version of a standard for quality SilverStripe modules.

* _config (for yml config)
* The module is a Composer package.
* All Composer dependencies are bound to a single major release (e.g. ~3.1 not >=3.1).
* There is a level of test coverage.

This comment has been minimized.

Copy link
@chillu

chillu Sep 28, 2015

Member

Capitalisation is a bit weird in this doc - e.g. Level should be lowercase here.

This comment has been minimized.

Copy link
@jonom

jonom Sep 28, 2015

Contributor

This is lowercase... did Github change the font they use for markdown? All the l's look like L's now. Compare: ls

This comment has been minimized.

Copy link
@chillu

chillu Sep 28, 2015

Member

Whoa, that's a weird representation of a lowercase l, but you're right!

This comment has been minimized.

Copy link
@camfindlay

camfindlay Sep 28, 2015

Author Contributor

Kool so not changes needed here then? ;)

This comment has been minimized.

Copy link
@chillu

chillu Sep 28, 2015

Member

Nope, all good.

* How to report security vulnerabilities. Note that PSR-9 / PSR-10 may be recommended once released.
* Security, license, links to more detailed docs.
* CONTRIBUTING.md
* A changelog CHANGELOG.md (may link to other more detailed docs if you want).

This comment has been minimized.

Copy link
@chillu

chillu Sep 28, 2015

Member

Github has a nice release feature where you can add release notes (stored as extended info in git tag), in addition to providing the full commit log. In this context, a CHANGELOG.md feels a bit backwards. We're also adding a lot of files to the module root. If a module authors chooses to use the Github release feature, they should just put a link in the README

This comment has been minimized.

Copy link
@camfindlay

camfindlay Sep 28, 2015

Author Contributor

I think this could be optional if people take advantage of the GH release feature. Though perhaps the changelog.md could link to this as a reminder?

This comment has been minimized.

Copy link
@tractorcow

tractorcow Sep 28, 2015

Contributor

I think it might be more useful for documentation systems (including, but not limited to, docsviewer) to have a markdown version of the file for publishing.

Github releases can still include this extended info.

* Has a licence (LICENSE.md file) - for SilverStripe supported this needs to be BSD.
* Detailed documentation in /docs/en as a nested set of GitHub-compatible Markdown files.
* Links and image references are relative, and are able to be followed in viewers such as GitHub.
* Page Metadata can be added to pages.

This comment has been minimized.

Copy link
@chillu

chillu Sep 28, 2015

Member

I'm not sure what this is referring to, can you explain?

This comment has been minimized.

Copy link
@camfindlay

camfindlay Sep 28, 2015

Author Contributor

Perhaps we can rephrase this. I think this was referring to docsviewer or GHPages markdown meta data at the top of md files to define things like title, description etc. Perhaps we don't explicitly require this.

This comment has been minimized.

Copy link
@tractorcow

tractorcow Sep 28, 2015

Contributor

How about markdown files may include non-visible comments or meta-data

* Testing/development instructions and a link to contrib instructions.
* How to report security vulnerabilities. Note that PSR-9 / PSR-10 may be recommended once released.
* Security, license, links to more detailed docs.
* CONTRIBUTING.md

This comment has been minimized.

Copy link
@stevie-mayhew

stevie-mayhew Sep 28, 2015

Contributor

I don't know if this is necessary for all small modules? Could just be a section within the README.md file? Most of the modules we have would likely have the same contributing guidelines, which could be standardized as part of the main SS docs about modules somewhere?

This comment has been minimized.

Copy link
@chillu

chillu Sep 28, 2015

Member

The contributing.md file has the advantage of showing up on the "new pull request" and "new issue" screen in Github, so a great way to engage new contributors and remind them of our conventions etc.

This comment has been minimized.

Copy link
@stevie-mayhew

stevie-mayhew Sep 28, 2015

Contributor

That I did not know! Ignore Stevie...

This comment has been minimized.

Copy link
@camfindlay

camfindlay Sep 28, 2015

Author Contributor

Yip @chillu is right. It's very handy and a place where you can put things like your contributor license agreement, links to community code of conduct etc about how the contribution process will work.

* Installation
* Configuration
* Usage guides for key features; screenshots are recommended.

This comment has been minimized.

Copy link
@jonom

jonom Sep 28, 2015

Contributor

Could this be highly recommended? I find it so much easier to judge the quality and usefulness of a module when screenshots are present.

This comment has been minimized.

Copy link
@camfindlay

camfindlay Sep 28, 2015

Author Contributor

Yip I like the screenshots, I think even just having this in here is a start (I wonder how many people actually are aware you can add screenshots in your composer.json file too). 👍

@camfindlay

This comment has been minimized.

Copy link
Contributor Author

commented Oct 18, 2015

Ok so the only outstanding issues here are as far as I can see...

  1. Change ~ to ^ for versions in composer.json
  2. Change the mention about markdown meta data to read "Markdown may include non-visible comments or meta-data"

I'll make these updates today and would be good to get this initially merged in to the 3.2 branch (I'll reopen a PR). Any further changes can be raise by further pull requests.

@camfindlay camfindlay closed this Oct 18, 2015

* All Composer dependencies are bound to a single major release (e.g. ~3.1 not >=3.1).
* There is a level of test coverage.
* A clear public API documented in the docblock tags.
* Recommend the use of [PSR-1](http://www.php-fig.org/psr/psr-1/) and [PSR-2](http://www.php-fig.org/psr/psr-2/).

This comment has been minimized.

Copy link
@stephenmcm

This comment has been minimized.

Copy link
@camfindlay

camfindlay Oct 19, 2015

Author Contributor

yip! Getting more of SS in line with PSR stuff makes sense for long term interop improvements. It raises a second question about changing the stated SS code conventions (that is another discussion to be had outside this one). Of course, it says recommended, you can of course still use the ss code conventions.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.