search

hoodiehq / discussion

General discussions and questions about Hoodie
7 stars 1 forks source link

The Hoodie Module Structure #77

Closed janl closed 8 years ago

janl commented 9 years ago

This is a sub-issue of https://github.com/hoodiehq/discussion/issues/76

(copied original text)

There are a bunch of changes we want to make to all the modules on http://github.com/hoodiehq. The prime objective here is to unify a few things across all repositories in a way that the development experience on each module, be it a CSS library, our website or core JavaScript code, is the same everywhere.

One thing we’d like to encourage and pioneer is the use of README.md files in all subdirectories, with information what the particular sub-part of a module is doing and why. That way, our code is much easier to navigate and learn.

In addition, where it makes sense, modules will generate and expose their automatically generated API documentation for pick-up by a central documentation location and for offline viewing.

We’d like to move away from grunt as a built tool because it is a bit unwieldy. We’ll be moving to npm scripts for our built scripting needs.

We want to standardise on a single set of commit message conventions for all the types of commits we have across all repos. And we want to enforce these with pre-commit hooks that have friendly error messages for newcomers to do the right thing.

This is a bit technical, but we found a neat solution to make this easy for everyone. A pre-commit hook is a piece of software that git runs to determine whether it should allow the user to make a commit. We want to use these hooks to ensure that all commit messages follow our standard format of type(scope): message with type and scope being from a strict set that has semantic meaning down the road of the lifecycle of a module.

Pre-commit hooks are something that each user has to install for themselves, they are not part of a git clone. In order to avoid everyone having to do this manually, we propose this procedure:

  1. all modules have a require new module, say hoodie-commit-hooks or hoodie-developer-tools.
  2. if the require fails, we print a nice message like “please run this command: `npm install -g hoodie-commit-hooks”.
  3. Now the require succeeds and it can install the pre-commit hook in the current repository.

Things we want to enforce with pre-commit hooks:

This should make the experience of contributing to a single module a lot more pleasant and remove a lot of the burden of reviewing and maintaining code from the existing developers.

janl commented 9 years ago

(we are updating this checklist while we are doing this for our first few modules, until the process is solid)

Usage: copy the raw source of this issue into the a new issue on module you want to migrate and start ticking off boxes.

Here is how we are going to do this:

For each repo, we:

Module Meta

Module Content

READMEs

Directory structure:

janl commented 9 years ago

(we are updating this checklist while we are doing this for our first few modules, until the process is solid)

Usage: copy the raw source of this issue into the a new issue on module you want to publish and start ticking off boxes.

Once we are done with every plugin and the new architecture can go live, we do this:

gr2m commented 8 years ago

I guess we can close this? If not, can we create a follow up issue of the points which are still relevant today?