1 # How to contribute to Teclib' CFPropertyList
3 Welcome to our ever-growing community :octocat:!
5 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.
7 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.
9 We present you here the guidelines to start contributing in any of the Teclib' projects.
11 # <a name="top"></a>Table of contents
13 - 1 [See what’s going on](#1)
14 - 1.1 [Issue Dashboard](#1.1)
15 - 1.2 [Pull Request Dashboard](#1.2)
17 - 2.1 [Contact us](#2.1)
18 - 2.2 [Customers Assistance](#2.2)
19 - 3 [Feature Requests](#3)
20 - 3.1 [Requirement for a Feature Request](#3.1)
21 - 3.1.1 [Major Feature Request](#3.1.1)
22 - 3.1.2 [Minor Feature Request](#3.1.2)
23 - 3.2 [Request a New Feature](#3.2)
25 - 4.1 [How to Submit an Issue or Bugs](#4.1)
26 - 4.1.1 [Check for Past Issues or Bugs](#4.1.1)
27 - 4.1.2 [Try to Reproduce It!](#4.1.2)
28 - 4.1.3 [Isolate the Problem](#4.1.3)
29 - 4.1.4 [Information Needed for the Report](#4.1.4)
30 - 4.1.5 [Submit an Issue](#4.1.5)
31 - 4.2 [How to Create a Pull Request (PR)](#4.2)
32 - 4.2.1 [Create a Branch and Naming it](#4.2.1)
33 - 4.2.2 [Make Changes](#4.2.2)
34 - 4.2.3 [Commit Your Changes](#4.2.3)
35 - 4.2.3.1 [Rules to Follow](#4.2.3.1)
36 - 4.2.3.2 [Commit Format](#4.2.3.2)
37 - 4.2.3.2.1 [Header: Writing a `type`](#4.2.3.2.1)
38 - 4.2.3.2.2 [Header: Writing the `(optional scope)`](#4.2.3.2.2 )
39 - 4.2.3.2.3 [Header: Writing a `description`](#4.2.3.2.3)
40 - 4.2.3.2.4 [Header Lenght](#4.2.3.2.4)
41 - 4.2.3.2.5 [Writing the `optional body`](#4.2.3.2.5)
42 - 4.2.3.2.6 [Writing the `optional footer`](#4.2.3.2.6)
43 - 4.2.3.3 [Commit Examples](#4.2.3.3)
44 - 4.2.4 [Push your Changes](#4.2.4)
45 - 4.2.5 [Create a Pull Request](#4.2.5)
46 - 4.2.5.1 [How to Write a Title for a Pull Request](#4.2.5.1)
47 - 4.2.5.2 [Before Send a Pull Request](#4.2.5.2)
48 - 4.2.5.3 [How We Check your Submission](#4.2.5.3)
49 - 4.2.5.3.1 [Status Check](#4.2.5.3.1)
50 - 4.2.5.3.2 [App/Bots List](#4.2.5.3.2)
51 - 4.2.6 [How to proceed with suggestions](#4.2.6)
52 - 5 [What to do next?](#5)
53 - 6 [Coding Rules](#6)
55 # <a name="1"></a> 1. See what's going on! [:top:](#top)
57 ## <a name="1.1"></a> 1.1 Issue Dashboard
58 If you want to know all the issues we're dealing with right now, take a look at our [Issue Dashboard](https://github.com/TECLIB/CFPropertyList/issues) and look for areas in which you can help.
61 ## <a name="1.2"></a> 1.2 Pull Request Dashboard
62 If you want to give us a hand solving issues then great, take a look at our [Pull Request Dashboard](https://github.com/TECLIB/CFPropertyList/pulls) and check for an open or closed PR. We don’t want to duplicate efforts.
64 # <a name="2"></a> 2. Assistance [:top:](#top)
66 ## <a name="2.1"></a> 2.1 Contact us
67 You can contact us through any of our channels, check our [Contact section](http://www.teclib-edition.com/en/contact-us/)
69 ## <a name="2.2"></a> 2.2 Customers Assistance
70 Use our official [support channel](https://support.teclib.com/).
72 # <a name="3"></a> 3. Feature Requests [:top:](#top)
74 ## <a name="3.1"></a> 3.1 Requirement for a Feature Request
75 If you like to _implement_ a new feature please [submit an Issue](https://github.com/TECLIB/CFPropertyList/issues/new) with a proposal, so we can be sure it's relevant.
77 ### <a name="3.1.1"></a> 3.1.1 Major Feature Request
78 For a major new feature request, [open an Issue](https://github.com/TECLIB/CFPropertyList/issues/new) and outline your proposal so it can be discussed.
80 ### <a name="3.1.2"></a> 3.1.2 Minor Feature Request
81 For a minor new feature request, you can craft it and directly [submit it as a Pull Request](https://github.com/TECLIB/CFPropertyList/pulls), we'll take care of it.
83 ## <a name="3.2"></a> 3.2 Request a New Feature
84 You can request a new feature by [submitting an Issue](https://github.com/TECLIB/CFPropertyList/issues/new)
86 # <a name="4"></a> 4. Submitting [:top:](#top)
88 ## <a name="4.1"></a> 4.1 How to Submit an Issue or Bugs
90 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.
92 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:
94 ### <a name="4.1.1"></a> 4.1.1 Check for Past Issues or Bugs
95 Before submitting the issue please check the [Issue Tracker](https://github.com/TECLIB/CFPropertyList/issues/), 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.
97 ### <a name="4.1.2"></a> 4.1.2 Try to Reproduce It!
98 Try to reproduce this issue/bug using the latest `develop` branch in the repository [Check it here](https://github.com/TECLIB/CFPropertyList/branches).
100 ### <a name="4.1.3"></a> 4.1.3 Isolate the Problem
101 Ideally, create a reduced test case. We prefer bug reports with small, portable test cases.
103 ### <a name="4.1.4"></a> 4.1.4 Information Needed for the Report
104 We require the following information:
106 * :warning: **Observed Results:** A brief description of the problem.
107 * :mag_right: **What steps will reproduce the issue?:** If suitable, including the steps required to reproduce the bug.
108 * :boom: **Expected Results:** What did you expect to happen?
110 ### <a name="4.1.5"></a> 4.1.5 Submit an Issue. :rocket:
111 Having all data at hand, file the new issue by filling out our [Issue form](https://github.com/TECLIB/CFPropertyList/issues/new).
113 **— That's it! :tada:**
115 ## <a name="4.2"></a> 4.2 How to Create a Pull Request (PR)
117 Before submitting your Pull Request check for an open or closed PR that relates to your submission. We don't want to duplicate efforts.
119 ### <a name="4.2.1"></a> 4.2.1 Create a Branch and Naming it
121 The project is organized according to the branch model [Git Flow.](http://nvie.com/posts/a-successful-git-branching-model/) 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.
123 :heavy_exclamation_mark: **Branch Name Format: `feature/my-killer-feature`**.
125 :no_entry_sign: **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.
127 ### <a name="4.2.2"></a> 4.2.2 Make Changes
129 Make your changes in your **newly created** branch.
132 git checkout -b feature/created-branch develop
135 ### <a name="4.2.3"></a> 4.2.3 Commit Your Changes
136 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.
138 ### <a name="4.2.3.1"></a> 4.2.3.1 Rules to Follow
139 For commits, we follow the [Conventional Commit](http://conventionalcommits.org/). 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.
141 ### <a name="4.2.3.2"></a> 4.2.3.2 Commit Format
142 Each commit message consists of a **header**, a **body**, and a **footer**. The header has a special
143 format that includes a **type**, a **scope**, and a **description**:
145 **:warning: Important:** Please avoid generic terms.
147 The commit message should be structured as follows:
150 type(optional scope): description
157 ### <a name="4.2.3.2.1"></a> 4.2.3.2.1 Header: Writing a `type`
158 Commits must be prefixed with a type, which consists of a verb, **feat, fix, build,** followed by a colon and space.
162 * **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm).
163 * **ci**: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs).
164 * **docs**: Documentation only changes.
165 * **feat**: A new feature.
166 * **fix**: A bug fix.
167 * **perf**: A code change that improves performance.
168 * **refactor**: A code change that neither fixes a bug or adds a feature.
169 * **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
170 * **test**: Adding missing tests or correcting existing tests.
173 >**Example for `type`:**
174 >:point_right:feat:point_left:(parser): add ability to parse arrays
177 ### <a name="4.2.3.2.2"></a> 4.2.3.2.2 Header: Writing the `(optional scope)`
178 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.
181 > **Example for a `(optional scope)`:**
182 > feat:point_right:(parser):point_left:: add ability to parse arrays
185 ### <a name="4.2.3.2.3"></a> 4.2.3.2.3 Header: Writing a `description`
186 A description must immediately follow the **`type(optional scope):`** The description is a short description of the commit.
189 * About commit character length, keep it concise and don't write more than **50 characters**.
190 * Use the imperative present tense: change, make, add, update, fix, etc; Do not use changed, changes, added, fixes, fixed, etc.
191 * Don't capitalize the first letter.
192 * Do not use a dot (.) at the end.
195 >**Example for `<description>`**:
196 >feat(parser)::point_right:add ability to parse arrays:point_left:
199 ### <a name="4.2.3.2.4"></a> 4.2.3.2.4 Header Lenght
200 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.
202 ### <a name="4.2.3.2.5"></a> 4.2.3.2.5 Writing the `optional body`
203 The body should include the motivation for the change and contrast this with previous behavior.
206 >**Example for `optional body`**:
209 remove out of date paragraph
214 ### <a name="4.2.3.2.6"></a> 4.2.3.2.6 Writing the `optional footer`
215 The `<optional footer>` should contain a [closing reference to an issue](https://help.github.com/articles/closing-issues-using-keywords/) if any.
217 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.
220 >**Example for `optional footer`**:
221 >:point_right:Closes #123:point_left:
224 ### <a name="4.2.3.3"></a> 4.2.3.3 Commit Examples
229 docs(readme): fix orthography, remove out of date paragraph and fix broken links
236 docs(readme): document design improvement change content
239 remove out of date paragraph
243 ### <a name="4.2.4"></a> 4.2.4 Push your Changes
244 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.
246 After working on your changes you need to Push it (upload) your **newly created branch** to GitHub
249 git push origin feature/created-branch
252 ### <a name="4.2.5"></a> 4.2.5 Create a Pull Request
254 Pull requests or PR are **proposed changes** to a repository submitted by a user and accepted or rejected by a repository's collaborators.
256 After all the work being pushed to the newly created branch, In GitHub, send a pull request to our [repository.](https://github.com/TECLIB/CFPropertyList/pulls)
258 ### <a name="4.2.5.1"></a> 4.2.5.1 How to Write a Title for a Pull Request
259 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.
261 **:warning: Important:** Please avoid generic terms.
264 **Title Length:** Keep it concise and don't write more than **50 characters** in the title.
267 **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](https://github.com/apps/wip) will set its status to error.
270 >**Example for `Titles for work in progress (WIP):`**
271 >:point_right:WIP Added a Table of Content for the Contributing Guideline Document.:point_left:
275 **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.
278 >**Example for `Titles for Finalized Work:`**
279 >:point_right:Added a Table of Content for the Contributing Guideline Document.:point_left:
282 ### <a name="4.2.5.2"></a> 4.2.5.2 Before Send a Pull Request
284 **1 - Pull Request Description:** Write a description about the changes, we provide a [template](https://github.com/TECLIB/CFPropertyList/community) for Pull Request descriptions. When you're creating a Pull Request it'll be shown automatically. Just fill it out and you're done.
286 **2 - Choose the right label**: Look at the [list of available labels.](https://github.com/TECLIB/CFPropertyList/issues/labels)
288 **3 - Smash that button!** Press that _Create Pull Request_ button and you're done.
290 **— That's it! :tada:**
292 ### <a name="4.2.5.3"></a> 4.2.5.3 How We Check your Submission
294 #### <a name="4.2.5.3.1"></a> 4.2.5.3.1 Status Check :rotating_light:
296 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.
298 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:
300 #### <a name="4.2.5.3.2"></a> 4.2.5.3.2 App/Bots List :traffic_light:
302 **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.
304 _WIP: Maintainers: Required / Contributors: Required_
306 **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.
308 _AccessLint: Maintainers: Required / Contributors: Required_
310 **commitlint:** Runs commitlint against all commits of new or edited pull requests and sets an appropriate status check.
312 _commitlint: Maintainers: Required / Contributors: Required_
314 **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.
316 _DCO: Maintainers: Required / Contributors: Optional_
318 **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.
320 _DEP: Maintainers: Required / Contributors: Required_
322 **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.
324 _ci/circleci build: Maintainers: Required / Contributors: Required_
326 **continuous-integration/travis-ci/push(and pr):** An automatic construction of the requested changes is carried out and the tests are executed automatically.
328 _continuous-integration/travis-ci/push(and pr): Maintainers: Required / Contributors: Required_
330 ### <a name="4.2.6"></a> 4.2.6 How to proceed with suggestions
332 If we suggest changes then:
333 * Make the required updates.
334 * Re-run the test suites to ensure tests are still passing.
335 * Rebase your branch and force push to your GitHub repository (this will update your Pull Request):
338 git rebase develop -i
342 **Remove the WIP label:** When a PR is ready for review, remove the prefix WIP in the PR title.
344 # 5. <a name="5"></a> What to do next? [:top:](#top)
346 After your pull request is merged, you can safely delete your branch and pull the changes
347 from the main (upstream) repository:
349 * Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:
352 git push origin --delete feature/created-branch
355 * Check out the develop branch:
358 git checkout develop -f
361 * Delete the local branch:
364 git branch -D feature/created-branch
367 * Update develop with the latest upstream version:
370 git pull --ff upstream develop
373 # 6. <a name="6"></a> Coding Rules [:top:](#top)
375 To ensure consistency throughout the source code, keep these rules in mind as you are working:
377 * All features or bug fixes must be tested by one or more specs (unit-tests).
378 * All methods must be documented.