Skip to content

Latest commit

 

History

History
149 lines (95 loc) · 5.91 KB

contributing.md

File metadata and controls

149 lines (95 loc) · 5.91 KB
Raw

Contributing to Blitz

First and foremost, thanks for your interest! 👍

The following is a set of guidelines for contributing to the blitz eBook framework, hosted in the FriendsOfEPUB Organization on Github. These are just guidelines, not rules, so feel free to propose changes to this document in a pull request.

Table of contents

  1. Design decisions
  2. How can I contribute?
  1. Roadmap

Design decisions

Please feel free to challenge every design decision we’ve made. Nothing is perfect, we respect the different opinions held on this complex subject and are open to discussion.

How can I contribute?

Reporting Bugs

First and foremost, check if your issue has already been reported (don’t forget to check closed issues too). If it has, add a comment to the existing issue instead of opening a new one.

Submitting a good bug report

Explain the problem and include additional details to help maintainers reproduce the problem:

  • Use a clear and descriptive title for the issue to identify the problem.
  • Tell which devices or Reading Systems are impacted—unfortunately, we don’t have access to a lot of devices so it makes debugging difficult.
  • Describe the exact steps which reproduce the problem in as many details as possible.
  • Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use Markdown code blocks.
  • Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
  • Explain which behavior you expected to see instead and why.
  • Include screenshots and/or animated GIFs which show you following the described steps and clearly demonstrate the problem.
  • If you’ve fixed the issue by yourself, tell us how you did it (snippet in a Markdown code block).

Provide more context by answering these questions:

  • Did the problem start happening recently (e.g. after updating to a new version of blitz) or was this always a problem?
  • If the problem started happening recently, can you reproduce the problem in an older version of blitz? What's the most recent version in which the problem doesn't happen? You can download older versions of blitz from the releases page.
  • Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.

Template for submitting bug reports

[Short description of problem here]

**Reproduction Steps:**

1. [First Step]
2. [Second Step]
3. [Other Steps...]

**Expected behavior:**

[Describe expected behavior here]

**Observed behavior:**

[Describe observed behavior here]

**Screenshots and GIFs**

![Screenshots and GIFs which follow reproduction steps to demonstrate the problem](url)

**Blitz version:** [Enter blitz version here]
**Device or reading System:** [Enter device or reading system here]

**Additional information:**

* Problem started happening recently, didn't happen in an older version of blitz: [Yes/No]
* Problem can be reliably reproduced, doesn't happen randomly: [Yes/No]

**Fix**

[Explain how you fixed it]

Suggesting enhancements

First and foremost, check if those enhancements have already been suggested (check issues) or addressed (check pull requests).

Submitting a good enhancement suggestion

  • Use a clear and descriptive title for the issue to identify the suggestion.
  • Provide a step-by-step description of the suggested enhancement in as many details as possible.
  • Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples, as Markdown code blocks.
  • Include screenshots and/or animated GIFs which help you demonstrate the steps or point out the part of Blitz which the suggestion is related to.
  • Explain why this enhancement would be useful to most Blitz users, the problems it solves as regards Reading Systems, design, etc.

Template for suggesting an enhancement

[Short description of suggestion]

**Steps which explain the enhancement**

1. [First Step]
2. [Second Step]
3. [Other Steps...]

**Current and suggested behavior**

[Describe current and suggested behavior here]

**Why would the enhancement be useful to most users**

[Explain why the enhancement would be useful to most users, the problem it solves, etc.]

**Screenshots and GIFs**

![Screenshots and GIFs which demonstrate the steps or part of Atom the enhancement suggestion is related to](url)

Your first code contribution

Unsure where to begin contributing to the blitz framework? You can start by looking through the help-wanted issues or the Roadmap section.

Then fork the repo and implement your modifications.

If needed, do not hesitate to ask questions. We’re here to help.

We’ll finally review your pull request to check if everything is OK.

Pull requests

  • QA new code (see official support list).
  • Please update from master before proposing a pull request so that we don’t have to deal with conflicts.
  • Use a clear and descriptive title.
  • List all fixes and enhancements the pull request provides.
  • Include screenshots and/or animated GIF whenever possible—no need to do that for correcting typos in docs for instance.
  • Document new code.

Roadmap

This basically is our TODO list.

  • Create Web Page
  • Improve docs
  • LESS Presets (novels, essays, kitchen books, poetry, etc.)
  • Web App
  • Test suite (in the form of EPUB + Kindle files)
  • Init JS Framework
  • Blitz a11y (i.e. implement debug mode for accessibility as a plugin)

As you can see, there’s quite a lot of stuff to deal with if you’re willing to contribute.