Skip to content

Latest commit

 

History

History
133 lines (97 loc) · 5.59 KB

CONTRIBUTING.md

File metadata and controls

133 lines (97 loc) · 5.59 KB
Raw

Contributing to Blackprint

First of all, thanks for taking the time to contribute!
To help you contribute to this project we have created some guidelines for our contributors.

Table of Content

Terms

Here are some terms that we will use in this repo:

  1. "Technology" is used to describe a software, libraries, tool, framework, etc...
  2. "Engine" refers to Blackprint Engine that run on some programming language.

What Contribution Do We Accept?

Any well-intentioned contribution is welcomed, for the example:

  1. Bug fixes
  2. New feature (please create issue with the use case to be reviewed first)
  3. Improve documentation or guidelines
  4. Financial contribution
  5. Promote and spread the words about Blackprint
  6. Joining the community and help other people

Requesting an Feature

To request an feature, you can create an issue in the repository. Please follow these simple guidelines:

  1. Search for other issues already requesting the feature
  2. If an issue doesn't exist, create an issue with the template on GitHub Issue
  3. Please create separate issues for each feature

Requesting Nodes

Blackprint Engine is available on some programming language. If you want to request Blackprint nodes for other technology (like library that developed by someone else) please create issue on their repository instead or ask the community.

You can use this template for start your first node for browser.

The Build Script: how it works

npm start: Run development server for Blackprint (Sketch + Editor + Nodes + Engine).
This will only compile .js, .html, .scss, .sf file extension.

  • Sketch library: /src
  • Engine library: /engine-js
    • If you want to only focus on this engine, please set compileEngineOnly on gulpfile.js to true
  • Editor: /example
  • Nodes: /nodes
    • Any folder with blackprint.config.js will be considered as Blackprint Addons and will be added to Editor automatically if it's not disabled

npm run compile: Compile, minify files, and run Babel for Blackprint (Sketch + Editor + Nodes + Engine).
This will only compile .js, .html, .scss, .sf file extension, similar with npm start.

You may want to see the guidelines if you want to use the Blackprint Editor.

Bundled file location

When you run the build script above you may get these files.

  • Sketch library: /dist/blackprint.min.js, /dist/blackprint.sf.js and /dist/blackprint.sf.css
  • Engine library: /engine-js/dist/engine.min.js
  • Editor: /example/assets/*.js and /example/assets/*.css
  • Nodes: /dist/*.mjs, /dist/*.sf.mjs, /dist/*.sf.css

The file names that has different export target:

  • *.sf.css and *.sf.mjs can only being imported/run on Browser
  • *.mjs is mjs module that can be imported for Deno

Blackprint Node and Interface Naming Conventions

Currently this is for JavaScript nodes.

The node and interface should be registered with capitalized letter with slash with following format:

  • Node: LibraryName/[Category or Feature name]/NodeName
  • Interface: BPIC/LibraryName/[Category or Feature name]/NodeName

BPIC: Blackprint Interface Component

The example below

// ------ Node ------
Blackprint.registerNode('Graphics/Converter/GIF', ...);
// You can easily find and create from the Blackprint Editor from the node list.
// Create from the editor menu: Graphics -> Converter -> GIF

// Create with JS
instance.createNode('Graphics/Converter/GIF'); // instance = sketch/engine object

// ------ IFace ------
Blackprint.registerInterface('BPIC/Graphics/Converter/GIF', ...);
// Blackprint will create the DOM Element with lowercased tag name: <bpic-graphics-converter-gif>

// Get the iface from the DOM
let iface = $('bpic-graphics-converter-gif')[0].model;
let node = iface.node;

// Get the iface from the engine instance
let myNode = instance.iface[id];

Version Conventions

Blackprint haven't follow semantic versioning before v1.0.0, you will need to specify the fixed version when using Blackprint Engine or Sketch library to avoid breaking changes.

The version naming follows the rules of given a version number vMAJOR.MINOR.PATCH, increment the:

MAJOR version will stay 0 until all roadmap has been completed.
MINOR version may has new feature or possible breaking changes.
PATCH version when you add functionality and bug fixes that backwards compatible.

A new release will be published when new feature are added or a bug was fixed. If the minor version is updated, please see the CHANGELOG.md to make sure the breaking changes doesn't affect your project.

Financial Contribution

Blackprint is a MIT licensed open source project and completely free to use.
However, the amount of effort needed to maintain and develop new features for the project is not sustainable without proper financial backing.

You can support Blackprint development financially from the link on repository's Sponsor button.