Skip to content

Commit

Permalink
Initial commit with code migrated from proof-of-concept stage
Browse files Browse the repository at this point in the history
  • Loading branch information
@shamasis
shamasis committed Feb 23, 2016
1 parent ba1cacc commit 656a9d7
Show file tree
Hide file tree
Showing 79 changed files with 6,430 additions and 1 deletion.
186 changes: 186 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,186 @@
# Contributing to Postman Collection SDK

## Command Reference

### `npm install -d`

### `npm test`

### `npm test-lint`

### `npm test-infra`

## Repository

### Structure

Directory | Summary
----------------|---------------------------------------------
`scripts` | All CI scripts (triggered by NPM run-script)
`lib` | Library source modules, tests and doc source
`tests` | All repository and lib test specifications
`bin` | Command line scripts
`examples` | Sample artefacts, fixtures and scripts

~~ to be documented further ~~

### Branching and Tagging Policy

This repository uses standard `git-flow` branch management policy/strategy. If you want to learn more on `git-flow`,
refer to [tutorial from Atlassian](https://www.atlassian.com/git/workflows#!workflow-gitflow) and more details at
[http://nvie.com/posts/a-successful-git-branching-model/](http://nvie.com/posts/a-successful-git-branching-model/).

> Deletion of `master` and `develop`.
> Rebasing on `master` is blocked.
## Preferred IDE

Please use an IDE with [EditorConfig](http://editorconfig.org/) support.

Things like using 120 character ruler, addition of end-of-file newline, cleaning up of trailing whitespace have been
configured in this project using `.editorconfig`.

## Commit Guidelines

The following best practices, coupled with a pinch of common-sense will keep the repository clean and usable in future.
The idea is that everything that goes into the repository is not for an individual, but someone else who will be
directly or indirectly affected by it.

### Check for errors before committing

Checking for errors should be done for each commit whether it is being pushed to remote or not.

First, you don't want to submit any whitespace errors. Git provides an easy way to check for this — before you commit,
run `git diff --check`, which identifies possible whitespace errors and lists them for you. If you run that command
before committing, you can tell if you're about to commit whitespace issues that may annoy other developers.

Secondly, you should ensure that your commit does not break builds. Run `npm test` on the repository to execute all
sanity and smoke tests. If any test fail, do not change the test to pass your commit. The tests were there with a
purpose. Discuss within your team to ensure that the changes that you do to test specs are valid. If you are adding a
new feature, accompanying them with new tests are a good practice.

### Atomic commits

Try to make each commit a logically separate changeset. If you can, try to make your changes digestible — don't code for
a whole weekend on five different issues and then submit them all as one massive commit on Monday. Even if you don't
commit during the weekend, use the staging area on Monday to split your work into at least one commit per issue, with a
useful message per commit. If some of the changes modify the same file, try to use `git add --patch` to partially stage
files. The project snapshot at the tip of the branch is identical whether you do one commit or five, as long as all the
changes are added at some point, so try to make things easier on your fellow developers when they have to review your
changes. This approach also makes it easier to pull out or revert one of the changesets if you need to later. There are
a number of useful Git tricks for rewriting history and interactively staging files — use these tools to help craft a
clean and understandable history.

### Clean commit message

*More detailed explanation includes your motivation for the change and contrast its implementation with previous
behavior — this is a good guideline to follow.*

Getting in the habit of creating quality commit messages makes using and collaborating with Git a lot easier. As a
general rule, your messages should start with a single line that’s no more than about 50 characters and that describes
the changeset concisely, followed by a blank line, followed by a more detailed explanation.

It's also a good idea to use the imperative present tense in these messages. In other words, use commands. Instead of
"I added tests for" or "Adding tests for," use "Add tests for."

You should see if your commit message answers the following questions:
Answer the following questions:

1. **Why is this change necessary?**
2. **How does it address the issue?**
3. **What side effects does this change have?**

The first question tells reviewers of your pull request what to expect in the commit, allowing them to more easily
identify and point out unrelated changes.

The second question describes, at a high level, what was done to affect change. If your change is obvious, you may be
able to omit addressing this question.

The third is the most important question to answer, as it can point out problems where you are making too many changes
in one commit or branch. One or two bullet points for related changes may be okay, but five or six are likely indicators
of a commit that is doing too many things.

A good commit message template

```
Short (50 chars or less) summary of changes with relevant project management issue ID.
More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line
is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from
the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two
together.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank lines in between, but
conventions vary here
```

Run `git log --no-merges` to see what a nicely formatted project-commit history looks like.

## Guidelines for sending a Pull Request

Commit to master branch and develop branch is locked. As such, `git-flow` for feature completion and release will not
work. Thus, the last steps of feature completion in `git-flow` will happen as a Pull Request from website.

1. Pull Request comment and commit comments should explicitly discuss what changes were made. The Pull Request reviewer
should not need to communicate out of scope of issue tracker and the pull request description in order to understand
what changes has been done.

2. Pull Request should not be accepted with a test failure. Ensure that `npm test` passes on the `head` of your feature
branch.

3. Ensure that your feature branch has been tested and if it is associated with issues from corresponding issue-tracker,
the issue must be in a "resolved" state, implying that the issue has been fully tested, and accepted for inclusion.

4. Pull Requests with merge conflict are very difficult to review. Ensure that the `head` of your feature branch is
either already merged with `develop` or has no conflict when it is merged with `develop`.

5. The turn around time to close Pull Request is directly proportional to the delta of changes done - more the change in
files, more time it would take. As such, if you anticipate a feature branch to have a large delta on feature
completion, break it into sub-issues of the issue-tracker, test them, close them, and then send PR for that branch.

6. Turn around time for Pull Request would get affected if commit messages are unclear.

7. If you have deadlines to ensure feature completion, send Pull Request ahead of time. Better still, ensure your
feature development timeline accounts for PR acceptance.

8. If you have mentioned issue tracker references in Pull Request description, the severity and priority of those issues
will be taken into account. Otherwise, no Pull Request will take priority over others already in queue - it is
first-pull first-merge!

## Documentation guidelines

~~ to be documented further ~~

## The CI Platform

The CI system is built as a bunch of bash scripts to execute a set of tasks. These scripts are meant to execute tasks
that can run on every local machine. In general, knowledge about these scripts are not necessary for development.

**The scripts are to be only accessed using `npm run <script name>`.** This ensures that the execution point of the
scripts (`pwd`) is always the repository root.

### Ensuring your commits will not fail build

> `npm test`
The script associated with `npm test` will run all tests that ensures that your commit does not break anything in the
repository. As such run `npm test` before you push.

~~ to be documented further ~~

### Accessing build log on CI server

~~ to be documented further ~~

### Accessing your build artifacts

All scripts output build artifacts to `./out`


---
*Sections of this document use excerpts from various books and the Internet.
[http://git-scm.com/book/](http://git-scm.com/book/) is one of the dominating influences.*
176 changes: 176 additions & 0 deletions LICENSE.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,176 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions.

"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.

"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.

"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.

"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.

"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.

"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.

"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).

"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.

"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."

"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.

3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:

(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and

(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and

(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and

(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.

You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.

5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS
Loading

0 comments on commit 656a9d7

Please sign in to comment.