Skip to content
This repository has been archived by the owner on Mar 25, 2021. It is now read-only.

Latest commit

 

History

History
367 lines (225 loc) · 16 KB

CONTRIBUTING.adoc

File metadata and controls

367 lines (225 loc) · 16 KB

🤩 Hello and Welcome!

First off, thank you for considering contributing to Biyete. It’s people like you that make Biyete such a great tool.

Feel welcome and read the following sections in order to know how to ask questions and how to work on something.

All members of our community are expected to follow our Code of Conduct. Please make sure you are welcoming and friendly in all of our spaces.

Biyete is a free/libre project and we love to receive contributions from our community — you! There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into Biyete itself.

Table of Contents

Please follow these guidelines

Following these guidelines helps to communicate that you respect the time of the developers managing and developing this project. In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.

Code of Conduct

Be friendly, be kind, be patient, have fun.

More or less in the spirit of Kind Communication Guidelines.

Please note that by using GitHub, you have also agreed to follow the GitHub Terms of Service which include guidelines on conduct.

Bug reports

If you think you have found a bug in Biyete, first make sure that you are testing against the latest version of Biyete (your issue may already have been fixed). If not, search our issues list on GitHub in case a similar issue has already been opened.

It is very helpful if you can prepare a reproduction of the bug. In other words, provide a small test case which we can run to confirm your bug. It makes it easier to find the problem and to fix it.

Provide as much information as you can. The easier it is for us to recreate your problem, the faster it is likely to be fixed.

Feature requests

If you find yourself wishing for a feature that doesn’t exist in Biyete, you are probably not alone. There are bound to be others out there with similar needs. Open an issue on our issues list on GitHub which describes the feature you would like to see, why you need it, and how it should work.

Who uses Biyete?

An updated list of Biyete users is kept on the Github wiki. Add yourself or your company if you use Biyete!.

Contributing code and documentation changes

If you would like to contribute a new feature or a bug fix to Biyete, please discuss your idea first on the Github issue. If there is no Github issue for your idea, please open one. It may be that somebody is already working on it, or that there are particular complexities that you should know about before starting the implementation. There are often a number of ways to fix a problem and it is important to find the right approach before spending time on a PR that cannot be merged.

We add the help wanted label to existing Github issues for which community contributions are particularly welcome, and we use the good first issue label to mark issues that we think will be suitable for new contributors.

Our Development Process

We use GitHub to sync code to and from our repository. We’ll use GitHub to track issues and feature requests, as well as accept pull requests.

In summary it can be described as:

  1. Fork the repo and create your branch from main (or another relevant branch).

  2. If you’ve added code that should be tested, add tests.

  3. If you’ve changed APIs, update the documentation.

  4. Ensure the test suite passes.

  5. Make sure your code lints.

  6. If you haven’t already, review the Contributor License Agreement ("CLA").

Github Flow Strategy

We use Github Flow. So all code changes happen through Pull Requests. Pull Requests are the best way to propose changes to the codebase. We actively welcome your Pull Requests (Or Merge Requests for Gitlab terminology fans).

Flow

  1. Create an issue detailing the new feature, fix or other related task.

  2. If the task is approved then begin by creating a new branch (off the current main branch or related branch).

  3. Create a new Pull Request as soon as possible (to ease visibility and avoiding possible duplicate work with other contributors).

  4. Begin sending commits to your branch. These commits does not need to follow commitizen format, as they will be squashed later in a single commit. Please commit as often as you wish, with any format you want.

  5. Ensure that your code is in sync with the main branch and have no conflicts with the latest version in the repo before the PR approval. Rebase often.

  6. Ensure to update the CHANGELOG with your changes.

  7. Ensure all your code passes the test suite and includes relevant tests if needed.

  8. When the PR is approved then all your commits would be squashed. The squashed commit message must follow the commitizen format and reference the issue. You can use a final commit that follows the commitizen format so it will become the final commit of the whole PR.

  9. Your branch will be merged and then deleted.

Branch Naming Convention

The branch must follow the format: <issue number>-<type>/<context>. No spaces, all lowercase, separate words with -.

<type> must be one of the following:

  • feat: A new feature

  • fix: A bug fix

  • docs: Documentation only changes

  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, typos, comments, etc)

  • refactor: A code change that neither fixes a bug nor adds a feature

  • perf: A code change that improves performance

  • test: Adding missing tests

  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

Example: 1-docs/bancoestado-purchase-notification-parser

Branch: main

This is the "development branch". Code here may have unexpected bugs and other related goodies of a cutting edge version. All bug fixes and new features should be based off this branch.

The version in this branch will be based off the latest production release version (with suffix -dev). And should not change until a new production release is made.

Example: 1.0.0-dev.

Branch: production

This is the "releases branch". When code is pushed to this branch it is considered "production ready" and a new version is released. This is well tested and stable code. A new tag with a version must be created in order to set the current release.

Tag Naming Convention

All tags will follow the format v<HUMAN>.<MAJOR>.<MINOR>.

This follows Romantic Versioning.

  • HUMAN version when you make any conceptual change, major rewrite, major documentation changes or any other change which requires additional HUMAN involvement.

  • MAJOR version when you make incompatible API changes.

  • MINOR version when you add functionality in a backwards-compatible manner, or fix with backwards-compatible bug fixes.

The final version number would be decided at the moment of release. It should always be greater than the previous number.

Fork and clone the repository

You will need to fork the main Biyete repository and clone it to your local machine. See github help page for help.

Further instructions are given below.

Submitting your changes

Once your changes and tests are ready to submit for review.

Test your changes

Run the test suite to make sure that nothing is broken.

Rebase your changes

Update your local repository with the most recent code from the main Biyete repository, and rebase your branch on top of the latest main branch. We prefer your initial changes to be squashed into a single commit. Later, if we ask you to make changes, add them as separate commits. This makes them easier to review. As a final step before merging we will either ask you to squash all commits yourself or we’ll do it for you.

Submit a pull request

Push your local changes to your forked copy of the repository and submit a pull request. In the pull request, choose a title which sums up the changes that you have made, and in the body provide more details about what your changes do. Also mention the number of the issue where discussion has taken place, eg "Closes #123".

Then sit back and wait. There will probably be discussion about the pull request and, if any changes are needed, we would love to work with you to get your pull request merged into Biyete.

Please adhere to the general guideline that you should never force push to a publicly shared branch. Once you have opened your pull request, you should consider your branch publicly shared. Instead of force pushing you can just add incremental commits; this is generally easier on your reviewers. If you need to pick up changes from main, you can merge main into your branch. A reviewer might ask you to rebase a long-running pull request in which case force pushing is okay for that request. Note that squashing at the end of the review process should also not be done, that can be done when the pull request is integrated via GitHub.

Contributor License Agreement ("CLA")

In order to accept your pull request, you must agree to this simple CLA.

Licenses

Unless stated otherwise all the artifacts in this project are under the following licenses. All your submissions are understood to be under the same licenses that covers the project.

All documentation and non source code artifacts are under

All source code files are dual licensed

Feel free to contact the maintainers if there is a concern.

Original creation

You represent that each of Your Contributions is Your original creation. You represent that your contribution submissions include complete details of any third-party license or other restriction (including, but not limited to, related patents and trademarks) of which you are personally aware and which are associated with any part of your contributions.

Support is optional

You are not expected to provide support for your contributions, except to the extent you desire to provide support. You may provide support for free, for a fee, or not at all.

Styleguides

JavaScript Styleguide

All JavaScript must adhere to JavaScript Standard Style (Semi standard, with semicolons). And use Prettier for automatic code formatting.

  • Prefer the object spread operator ({…​anotherObj}) to Object.assign()

  • Inline `export`s with expressions whenever possible

  // Use this:
  export default class ClassName {

  }

  // Instead of:
  class ClassName {

  }
  export default ClassName

  • Place requires in the following order:

    • Built in Node Modules (such as path)

    • Local Modules (using relative paths)

  • Place class properties in the following order:

    • Class methods and properties (constructor, methods starting with static)

    • Instance methods and properties

General documentation with asciidoc

Any documentation should contain asciidoc syntax for formatting. Generally, you can use any asciidoc feature.

Headings

Only use h2 headings and lower, as the page title is set in h1. Also make sure you follow the heading hierarchy. This ensures correct table of contents are created.

Code blocks

In line code can be specified by enclosing the code in back-ticks (`). A block of multi-line code can be enclosed in triple back-ticks (```) but it is formatted better if it is enclosed in <pre>…​</pre> tags and the code lines themselves are indented.

Git Commit Guidelines

We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history.

To ease this way of commit messages we use Commitizen and Angular JS Commit Guidelines via Conventional Changelog.

Commit Message Format

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Any line of the commit message cannot be longer 100 characters!. This allows the message to be easier to read on GitHub as well as in various Git tools.

Type

Must be one of the following:

  • feat: A new feature

  • fix: A bug fix

  • docs: Documentation only changes

  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)

  • refactor: A code change that neither fixes a bug nor adds a feature

  • perf: A code change that improves performance

  • test: Adding missing tests

  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

Scope

The scope could be anything that helps specifying the scope (or feature) that is changing.

Examples - select(multiple): - dialog(alert):

Subject

The subject contains a succinct description of the change:

  • use the imperative, present tense: "change" not "changed" nor "changes"

  • don’t capitalize first letter

  • no dot (.) at the end

Body

Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes" The body should include the motivation for the change and contrast this with previous behavior.

Footer

The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit Closes, Fixes, or Relates to.

Breaking Changes are intended to be highlighted in the ChangeLog as changes that will require community users to modify their code after updating to a version that contains this commit.

Sample Commit messages:
fix(autocomplete): don't show the menu panel when readonly

this could sometimes happen when no value was selected

Fixes #11231
feat(chips): trigger ng-change on chip addition/removal

* add test of `ng-change` for `md-chips`
* add docs regarding `ng-change` for `md-chips` and `md-contact-chips`
* add demo for ng-change on `md-chips`
* add demo for ng-change on `md-contact-chips`

Fixes #11161 Fixes #3857
refactor(content): prefix mdContent scroll- attributes

    BREAKING CHANGE: md-content's `scroll-` attributes are now prefixed with `md-`.

    Change your code from this:

    <md-content scroll-x scroll-y scroll-xy>

    To this:

    <md-content md-scroll-x md-scroll-y md-scroll-xy>