Skip to content

Latest commit

 

History

History
174 lines (115 loc) · 4.98 KB

CONTRIBUTING.md

File metadata and controls

174 lines (115 loc) · 4.98 KB
Raw

Contributing to Plaiceholder

Welcome, and thanks for your interest in contributing! Please take a moment to review the following:

Architecture

Plaiceholder uses PNPM to develop multiple packages together as a monorepo. These packages are split across three directories:

  1. docs
  2. packages/
    • Publicly-consumable packages, published to npm
    • Each package is scoped to the @plaiceholder/ npm org.
  3. examples/
    • Non-published packages, primarily for demo-purposes but also for integration testing.
    • Examples are deployed to Vercel.
    • Each package is prefixed with example-with-

All @types/ and shared devDependencies should be installed to the root package.json

Style Guide

Getting Started

Setup

  1. Fork the repo and clone to your machine.
  2. Create a new branch with your contribution.
  3. Install pnpm on your machine.
  4. In the repo, install dependencies and link packages via: 
    pnpm install

Running Scripts

Scripts in the root package.json can be run via:

pnpm <script-name>

Individual package scripts can be run in the project root via:

pnpm <script-name> --filter <package-name>

Releases

A trade-off with using a personal repo is that permissions are fairly locked-down. In the mean-time releases will be made manually by the project owner.

Releases and versioning are handled by Changesets.

Adding Changesets

pnpm changeset

Publishing

  1. Switch into the default branch

    git checkout main

  2. Bump packages and generate CHANGELOG.mds based on the previously specified changesets.

    pnpm changeset version

  3. Prepare packages and regenerate the lockfile

    pnpm install

  4. Create a commit with the shared version, and push

    git commit vX.X.X

  5. Publish all packages to npm

    pnpm publish -r

  6. Create a tag with the shared version, then push the commit and tag

    git tag vX.X.X
git push
git push origin refs/tags/vX.X.X

  7. Create a release, using the newly pushed tag

Implementations

So, you want to build an alternative Plaiceholder implementation? Great!

Let's get started…

Requirements

Please respect that Plaiceholder is just the end result – countless hours of work have gone into making this project, almost all of it in the "free time" of its maintainers.

When building your own implementation, you should meet the following requirements:

  • Branding

    • ❌ Don't use the "Plaiceholder" name on its own, the logo, tagline or any of the marketing copy from plaiceholder.co. The "Plaiceholder" project is a trading name of "Big Attic OÜ", and therefore should not be confused with affiliation.
    • ✅ Do name your project with the -plaiceholder suffix or plaiceholder- prefix. e.g. your repo or package, could be called rust-plaiceholder, your function could be called rustPlaiceholder (but not plaiceholder).

  • Credit

    • ❌ Don't mislead others into thinking your implementation is original.

    • ✅ Do

      1. Link to the original source, documentation, or site, regularly and where relevant.

      2. Add the following disclaimer to the top of your README.md

        <p align="center">
  An externally-maintained implementation of
  <strong>
     <a href="https://github.com/joe-bell/plaiceholder">
        Plaiceholder
     </a>
  </strong>
</p>

---

<!-- your readme content-->

      3. Use the Apache-2.0 License.

      4. Add a License disclaimer to the bottom of your README.md

        ## License

Apache-2.0 License © <!-- your project name -->

### Acknowledgements

#### [Joe Bell](https://github.com/joe-bell) ([Plaiceholder](https://github.com/joe-bell/plaiceholder))

Copyright © 2020-2022, Joe Bell. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License").

If you have any questions above the above requirements, please feel free to reach out to the maintainers directly.

Raise a PR

Once you've completed the above, raise a PR to add your implementation to the Community page.