CONTRIBUTING.md

Contributing

Contributions, issues and feature requests are very welcome. If you are using this package and fixed a bug for yourself, please consider submitting a PR! Also, you can ping me on Twitter.

Guidelines

If you are planning to submit a pull request, it's very important to follow these basic rules:

Getting started

Fork the project on Github.

Clone the project from the fork you have created previously at first step.

Then, check out the project:

$ git clone https://github.com/your-github-user/docz.git

Setup

Pre-requisites

• Node: ^9.0.0 or higher
• Npm: 6.0.0 or higher
• Yarn: (optional) ^1.7.0 or higher

Install

Go to docz directory after checking out the repository:

$ cd docz

Then run the following commands to bootstrap all dependencies:

With yarn:

$ yarn install
$ yarn bs

With npm:

$ npm install
$ npm run bs

Finally, run the packages script to format, build and lint all packages:

With yarn:

$ yarn packages

With npm:

$ npm run packages

Developing

Project structure

docz follows the Monorepo design managed by Lerna.

The are just two directories to care about if you would like to contribute:

• Packages: Host all docz source code.
• Examples: Host all available usage examples.

Packages

There are lots of packages that are necessary to run docz, the most important packages that are important to care about:

docz-core

• This is the core of docz. All build algorithms, server process and parses belongs to here.
• If you break this package, probably you'll break all packages! Please, be carefull.
• All cli commands are built here and imported on docz package using ./bin script.
• Do not create scripts that's running on browser here, only node scripts.

docz

• Main and top level package.
• Scripts that's running on browser belongs to this package
• Built-ins components are built here, most specifically on this folder
• This package shouldn't have any component style, just boilerplate and logic!

Watching projects

To speed up your developing we recommended to run packages in a separated terminal process.

• Split your terminal and open each package directory in a separate window.
• Run yarn dev (or npm run dev) in each slice (or window) to watch tasks.

For example, to run some example from examples directory.

In the above example you're watching docz, docz-core and docz-theme-default and also running docz-example-basic. So any modifications made to any of those packages will reflect in basic example on the fly!

Creating plugins

If there are some plugin that you want to create, please contact me before to talk about the possibility to make this plugin official!

Commit messages

Commit messages should follow the commit message convention so, changelogs could be generated automatically by that. Commit messages are validated automatically upon commit. If you aren't familiar with the commit message convention, you can use yarn commit (or npm run commit) instead of git commit, which provides an interactive CLI for generating proper commit messages.

Pull Requests

• All pull requests have to be send against dev branch.

• The master branch is a snapshot of the latest stable release. All development should be done in dedicated branch. Do not submit PRs against the master branch.

• If you are checking out from a feature or a topic different of master or dev, you have to merge back and push against the same feature.

• Work in the src folder of respective package and DO NOT checkin dist in the commits.

• It's OK - and a very nice thing - to have multiple small commits as you work on the PR - we will let GitHub automatically squash it before merging.

If adding a new feature:

• Make sure that all examples are running as expected
• Provide convincing reason to add this feature. Ideally you should open a suggestion issue first and have it greenlighted before working on it.

Contributors

Thanks goes to these wonderful people (emoji key):

Pedro Nauck 💻 📖 🐛 👀