Skip to content

Latest commit

 

History

History
380 lines (262 loc) · 17.8 KB

CONTRIBUTING.md

File metadata and controls

380 lines (262 loc) · 17.8 KB
Raw

How to contribute to Teclib' Swift Framework Template

Welcome to our ever-growing community :octocat:!

Teclib’ is an open source software editor that offers a vast range of fully integrated open source technology packages, to better respond to business needs.

We are more than happy to accept external contributions to the project in the form of feedback, translations, bug reports, and even better, pull requests.

We present you here the guidelines to start contributing in any of the Teclib' projects.

Table of contents

1. See what's going on! 🔝

1.1 Issue Dashboard

If you want to know all the issues we're dealing with right now, take a look at our Issue Dashboard and look for areas in which you can help.

1.2 Pull Request Dashboard

If you want to give us a hand solving issues then great, take a look at our Pull Request Dashboard and check for an open or closed PR. We don’t want to duplicate efforts.

2. Assistance 🔝

2.1 Contact us

You can contact us through any of our channels, check our Contact section

2.2 Customers Assistance

Use our official support channel.

3. Feature Requests 🔝

3.1 Requirement for a Feature Request

If you like to implement a new feature please submit an Issue with a proposal, so we can be sure it's relevant.

3.1.1 Major Feature Request

For a major new feature request, open an Issue and outline your proposal so it can be discussed.

3.1.2 Minor Feature Request

For a minor new feature request, you can craft it and directly submit it as a Pull Request, we'll take care of it.

3.2 Request a New Feature

You can request a new feature by submitting an Issue

4. Submitting 🔝

4.1 How to Submit an Issue or Bugs

A good Issue/Bug report shouldn't leave others needing to chase you up for more information. Please try to be as detailed as possible in your report. What is your environment? What steps will reproduce the issue? What would you expect to be the outcome? All these details will help people to fix any potential bugs.

A bug is a demonstrable problem that is caused by the code in the repository. Good bug reports are extremely helpful, here are steps to follow to build a good one:

4.1.1 Check for Past Issues or Bugs

Before submitting the issue please check the Issue Tracker, maybe the issue/bug was already reported by another contributor. By doing this you help us maximize the effort spent on solving problems and the addition of new features.

4.1.2 Try to Reproduce It!

Try to reproduce this issue/bug using the latest develop branch in the repository Check it here.

4.1.3 Isolate the Problem

Ideally, create a reduced test case. We prefer bug reports with small, portable test cases.

4.1.4 Information Needed for the Report

We require the following information:

  • ⚠️ Observed Results: A brief description of the problem.
  • 🔎 What steps will reproduce the issue?: If suitable, including the steps required to reproduce the bug.
  • 💥 Expected Results: What did you expect to happen?

4.1.5 Submit an Issue. 🚀

Having all data at hand, file the new issue by filling out our Issue form.

— That's it! 🎉

4.2 How to Create a Pull Request (PR)

Before submitting your Pull Request check for an open or closed PR that relates to your submission. We don't want to duplicate efforts.

4.2.1 Create a Branch and Naming it

The project is organized according to the branch model Git Flow. Create a new branch before committing any changes. A branch is a parallel version of a repository. It is contained within the repository but does not affect the primary or master branch.

❗ Branch Name Format: feature/my-killer-feature.

🚫 Important: Do not commit to our default develop branch. Name it anything except master, develop, release-, or hotfix-. We'll use created-branch an example.

4.2.2 Make Changes

Make your changes in your newly created branch.

    git checkout -b feature/created-branch develop

4.2.3 Commit Your Changes

A commit, or "revision", is an individual change to a file (or set of files). It's like when you save a file, except with Git, every time you save it creates a unique ID (a.k.a. the "SHA" or "hash") that allows you to keep a record of what changes were made when and by who. Commits usually contain a commit message which is a brief description of what changes were made.

4.2.3.1 Rules to Follow

For commits, we follow the Conventional Commit. This leads to more readable messages that are easy to follow when looking through the project history. But also, we use the git commit messages to automatically generate changelogs from these messages.

4.2.3.2 Commit 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 description:

⚠️ Important: Please avoid generic terms.

The commit message should be structured as follows:

type(optional scope): description
<blank line>
optional body
<blank line>
optional footer

4.2.3.2.1 Header: Writing a type

Commits must be prefixed with a type, which consists of a verb, feat, fix, build, followed by a colon and space.

Your options:

  • build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm).
  • ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs).
  • docs: Documentation only changes.
  • feat: A new feature.
  • fix: A bug fix.
  • perf: A code change that improves performance.
  • refactor: A code change that neither fixes a bug or adds a feature.
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
  • test: Adding missing tests or correcting existing tests.

Example for type: 👉feat👈(parser): add ability to parse arrays

4.2.3.2.2 Header: Writing the (optional scope)

Refers to the extent, subject matter or contextual information about your changes. A scope is a phrase describing the file modified or a section of the codebase, it’s always enclosed in parenthesis.

Example for a (optional scope): feat:point_right:(parser):point_left:: add ability to parse arrays

4.2.3.2.3 Header: Writing a description

A description must immediately follow the type(optional scope): The description is a short description of the commit.

Important

  • About commit character length, keep it concise and don't write more than 50 characters.
  • Use the imperative present tense: change, make, add, update, fix, etc; Do not use changed, changes, added, fixes, fixed, etc.
  • Don't capitalize the first letter.
  • Do not use a dot (.) at the end.

Example for <description>: feat(parser)::point_right:add ability to parse arrays:point_left:

4.2.3.2.4 Header Lenght

The header cannot be longer than 100 characters. This allows the message to be easier to read on GitHub as well as in various git tools.

4.2.3.2.5 Writing the optional body

The body should include the motivation for the change and contrast this with previous behavior.

Example for optional body:

fix orthography
remove out of date paragraph
fix broken links

4.2.3.2.6 Writing the optional footer

The <optional footer> should contain a closing reference to an issue if any.

For example, to close an issue numbered 123, you could use the phrases Closes #123 in your pull request description or commit message. Once the branch is merged into the default branch, the issue will close.

Example for optional footer: :point_right:Closes #123:point_left:

4.2.3.3 Commit Examples

💩 Bad

docs(readme): fix orthography, remove out of date paragraph and fix broken links

👍 Good

docs(readme): document design improvement change content

fix orthography
remove out of date paragraph
fix broken links

4.2.4 Push your Changes

Pushing refers to sending your committed changes to a remote repository, such as a repository hosted on GitHub. For instance, if you change something locally, you'd want to then push those changes so that others may access them.

After working on your changes you need to Push it (upload) your newly created branch to GitHub

    git push origin feature/created-branch

4.2.5 Create a Pull Request

Pull requests or PR are proposed changes to a repository submitted by a user and accepted or rejected by a repository's collaborators.

After all the work being pushed to the newly created branch, In GitHub, send a pull request to our repository.

4.2.5.1 How to Write a Title for a Pull Request

Pull Request should be named in reference to the main fix or feature you provide; minor information can be added to the description. Please be specific and don't use generic terms.

⚠️ Important: Please avoid generic terms.

📏 Title Length: Keep it concise and don't write more than 50 characters in the title.

🚧 For Work in Progress (WIP): If you don’t want your PR to be merged accidentally, add the word "wip" or "WIP" to its title and the WIP bot will set its status to error.

Example for Titles for work in progress (WIP): 👉WIP Added a Table of Content for the Contributing Guideline Document.👈

✅ Finalized Work: If you are done with your work and want it to be merged, just write a descriptive title with no more than 50 characters.

Example for Titles for Finalized Work: 👉Added a Table of Content for the Contributing Guideline Document.👈

4.2.5.2 Before Send a Pull Request

1 - Pull Request Description: Write a description about the changes, we provide a template for Pull Request descriptions. When you're creating a Pull Request it'll be shown automatically. Just fill it out and you're done.

2 - Choose the right label: Look at the list of available labels.

3 - Smash that button! Press that Create Pull Request button and you're done.

— That's it! 🎉

4.2.5.3 How We Check your Submission

4.2.5.3.1 Status Check 🚨

Required status checks ensure us that all required tests are passing before collaborators can make changes to a protected branch. We enforce status checks before a branch is merged.

The type of required status check we choose is Loose, not all of them are required but some of them determines whether your changes will be reviewed or not. Some of them are here on this list, although, some of them may not be implemented in all repositories:

4.2.5.3.2 App/Bots List 🚥

WIP: Refers to Work In Progress, this app helps you to prevent your PR to be merged accidentally, add the word "wip" or "WIP" to its title and WIP bot will set its status to error. When you write WIP in the PR title it means that your changes are still in progress or unfinished, so it won't be reviewed until the WIP is removed.

WIP: Maintainers: Required / Contributors: Required

AccessLint: When a pull request is opened, AccessLint reviews the changes and comments with any new accessibility issues, giving you quick, timely, and targeted feedback, before code goes live.

AccessLint: Maintainers: Required / Contributors: Required

commitlint: Runs commitlint against all commits of new or edited pull requests and sets an appropriate status check.

commitlint: Maintainers: Required / Contributors: Required

DCO: This App enforces the Developer Certificate of Origin (DCO) on Pull Requests. It requires all commit messages to contain the Signed-off-by line with an email address that matches the commit author.

DCO: Maintainers: Required / Contributors: Optional

DEP: A Github App that helps to manage Pull Request dependencies. That App works similar to typical CI services ( e.g Travis) but instead of running a test suite, It will check whether a pull request dependencies are resolved.

DEP: Maintainers: Required / Contributors: Required

ci/circleci build: CircleCI acts as a platform for both Continuous Integration and Continuous Deployment. If your tests pass, then you can deploy your code to development, staging, production, or other environments.

ci/circleci build: Maintainers: Required / Contributors: Required

continuous-integration/travis-ci/push(and pr): An automatic construction of the requested changes is carried out and the tests are executed automatically.

continuous-integration/travis-ci/push(and pr): Maintainers: Required / Contributors: Required

4.2.6 How to proceed with suggestions

If we suggest changes then:

  • Make the required updates.

  • Re-run the test suites to ensure tests are still passing.

  • Rebase your branch and force push to your GitHub repository (this will update your Pull Request):

    git rebase develop -i
git push -f

⚠️ Remove the WIP label: When a PR is ready for review, remove the prefix WIP in the PR title.

5. What to do next? 🔝

After your pull request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:

  • Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:

    git push origin --delete feature/created-branch

  • Check out the develop branch:

    git checkout develop -f

  • Delete the local branch:

    git branch -D feature/created-branch

  • Update develop with the latest upstream version:

    git pull --ff upstream develop

6. Coding Rules 🔝

To ensure consistency throughout the source code, keep these rules in mind as you are working:

  • All features or bug fixes must be tested by one or more specs (unit-tests).
  • All methods must be documented.

Good luck! 🎉