Skip to content

Latest commit

 

History

History
132 lines (105 loc) · 4.37 KB

CONTRIBUTING.md

File metadata and controls

132 lines (105 loc) · 4.37 KB
Raw

Contributing to Bloc

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

The following is a set of guidelines for contributing to Bloc and its packages. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Proposing a Change

If you intend to change the public API, or make any non-trivial changes to the implementation, we recommend filing an issue. This lets us reach an agreement on your proposal before you put significant effort into it.

If you’re only fixing a bug, it’s fine to submit a pull request right away but we still recommend to file an issue detailing what you’re fixing. This is helpful in case we don’t accept that specific fix but want to keep track of the issue.

Creating a Pull Request

Before creating a pull request please:

  1. Fork the repository and create your branch from master.
  2. Install all dependencies (flutter packages get or pub get).
  3. Squash your commits and ensure you have a meaningful commit message.
  4. If you’ve fixed a bug or added code that should be tested, add tests! Pull Requests without 100% test coverage will not be approved.
  5. Ensure the test suite passes.
  6. If you've changed the public API, make sure to update/add documentation.
  7. Format your code (dart format .).
  8. Analyze your code (dart analyze --fatal-infos --fatal-warnings .).
  9. Create the Pull Request.
  10. Verify that all status checks are passing.

While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.

Contributing to Documentation

If you would like to contribute to the documentation please follow the same process for "Creating a Pull Request" and double check that your changes look good by running the docs locally.

# change directories into docs
cd ./docs

# run a local http server on port 8080
python3 -m http.server 8080

# navigate to http://localhost:8080

If you want to help maintain translations in the future, add yourself to .github/DOCS_ISSUE_TEMPLATE.md.

Tips

Here are a few tips when contributing to the documentation:

  • We use docsify for document rendering. Refer to the docsify documentation for more context/examples regarding the syntax, usage, and capabilities.
  • We prefer to reference real files in GitHub rather than creating snippets (some old examples make use of snippets but we are slowly migrating away). This is to keep the docs in sync if we modify the tutorial.
    • If the code changes but the tutorial doesn't get updated, we also get out of sync. To avoid this, you might add a section linking to a specific commit/version that reflects the state of the tutorial at the time you write the doc.

Pull requests

To make PRs more readable, please provide this checklist to the PR description so other contributors can easily see what's already done.

- [ ] README
- [ ] Cover page
- [ ] Sidebar
- Introduction
  - [ ] Getting Started
  - [ ] Why Bloc?
- Core Concepts
  - [ ] bloc
  - [ ] flutter_bloc
- [ ] Architecture
- [ ] Testing
- [ ] Naming Conventions
- [ ] FAQs
- Tutorials
  - Flutter
    - [ ] Counter
    - [ ] Timer
    - [ ] Infinite List
    - [ ] Login
    - [ ] Weather
    - [ ] Todos
    - [ ] Firebase Login
    - [ ] Firestore Todos
  - AngularDart
    - [ ] Counter
  - Flutter + AngularDart
    - [ ] Github Search
- Recipes
  - Flutter
    - [ ] Show SnackBar
    - [ ] Navigation
    - [ ] Bloc Access
- Tools
  - Extensions
    - [ ] IntelliJ
    - [ ] VSCode

Adding an example

Examples live in the examples folder.

When you're adding an example, make sure to add CI checks for it in main.yaml:

  • For a Flutter example, add it to the folder list in the examples-flutter step.
  • For a web example, add it to the folder list in the examples-web step.
  • For a pure Dart example, add it to the folder list in the examples-pure step.

Getting in Touch

If you want to just ask a question or get feedback on an idea you can post it on Discord.

License

By contributing to Bloc, you agree that your contributions will be licensed under its MIT license.