FuncUnit is managed by the DoneJS Contributors Team.
All contributions from all types of contributors are welcome. Contributing
to an Open Source project can be an intimidating experience. We're
committed to making the experience as pleasant and rewarding as possible. We're happy to setup a
pairing session to show you how to fix a bug or write a feature.
If you have any questions, you can always reach us on Slack.
When creating an issue, it's very helpful to include:
Small examples using tools like JSBin.
Breaking unit tests (optional).
Proposed fix solutions (optional)
Also, please search for previous tickets. If there's something similar, add to that, or
give it a +1.
Finally, if there are any questions, reach out to
us on the Bitovi forums or talk to us on
Slack.
Priority, Tags, and Complexity
The core team reviews issues
and assigns them a P0 to P4 tag corresponding to the following priorities:
P0 - An issue that will preempt any other issues currently being worked on.
P1 - A critical feature or bug that needs to be fixed to keep CanJS's high degree of quality.
P2 - A feature or bug that is less likely to be encountered, but something we intend to get to.
P3 - A nice to have. The OS team might get to it, but it's helpful if the community assists.
P4 - A nice to have that the OS team will accept, but will be unlikely to prioritize any effort towards.
There are several ways to influence these priorities:
Offer to pair with a contributor on a solution.
Write a good test.
Come to a DoneJS Contributors meeting and make your case.
Get others from other organizations to +1 the issue.
Make your case on Slack with a contributor or in the issue.
You can always hire Bitovi or a contributor to make the change.
Also, the core team will often include a complexity indicator in the title that looks like
~NUMBER. This is a fibonacci number. ~1 means its an extremely simple task. ~8 is about
a half day task. ~34 might take a week of experimentation.
Suggest a feature
FuncUnit uses Github Issues to track feature requests.
When creating an feature issue, it's very helpful to include:
Examples of what using the feature will look like.
Benefits and drawbacks of the feature.
Why the feature is important.
Any implementation details around the feature.
Here are some examples of well-written feature requests:
Also, please search for previous feature requests. If there's something similar, add to that, or
give it a +1.
Finally, if there are any questions, reach out to
us on the Bitovi forums or talk to us on
Slack.
Priority, Tags, and Complexity
The core team reviews issues
and assigns them a P0 to P4 tag corresponding to the following priorities:
P0 - An issue that will preempt any other issues currently being worked on.
P1 - A critical feature or bug that needs to be fixed to keep CanJS's high degree of quality.
P2 - A feature or bug that is less likely to be encountered, but something we intend to get to.
P3 - A nice to have. The OS team might get to it, but it's helpful if the community assists.
P4 - A nice to have that the OS team will accept, but will be unlikely to prioritize any effort towards.
There are several ways to influence these priorities:
Offer to pair with a contributor on a solution.
Write a good test.
Come to a DoneJS Contributors meeting and make your case.
Get others from other organizations to +1 the issue.
Make your case on Slack with a contributor or in the issue.
You can always hire Bitovi or a contributor to make the change.
Also, the core team will often include a complexity indicator in the title that looks like
~NUMBER. This is a fibonacci number. ~1 means its an extremely simple task. ~8 is about
a half day task. ~34 might take a week of experimentation.
Code changes
Contributing to any Open Source project can be intimidating. All contributions from all types of contributors are welcome. We're
committed to making the experience as pleasant and rewarding as possible. We're happy to setup a
pairing session to show you how to fix a bug or write a feature.
If you have any questions, you can always reach us on Slack.
There are a variety of ways to get a git command line client
connected to your GitHub account. Fortunately, GitHub has
great documentation on how to Setup Git.
Download Node.js version 4 or later at https://nodejs.org. You can
verify node is working at its version with:
> node -v
Get Firefox
Download the Firefox browser
here. Make sure it gets installed into the
default location for your operating system.
Firefox is used to run each repository's tests.
Getting the code and verify it is working
Once your environment is setup, you should be able to clone the repository you
want to change, install its dependencies, and verify you've setup your
development environment correctly.
1. Fork the repository you are working from by clicking the fork button.
2. Clone the your forked version of the repository.
Before the next step, make sure you move into your project's directory. For example:
> cd funcunit
3. Install npm dependencies with:
> npm install
4. Make sure Firefox is closed and run the test suite with:
> npm test
If every test passed, congrats! You have everything you need to
change code and send it back to us.
File organization and responsibilities
Understanding the file structure can help you figure out what code needs to be changed.
The following details the directory structure of FuncUnit:
├── package.json - Configuration of package and dev scripts
├── funcunit.js - Main module code
├── build.js - Build script to export code in other formats
├── .editorconfig - Configures editors for this project
├── .gitignore - Tells git to ignore certain files
├── .jshintrc - Configures JSHint
├── .npmignore - Tells npm publish to ignore certain files
├── .travis.yml - Travis CI configuration
├── publish-docs.js - Publishes the documentation to gh-pages
├── readme.md - Automatically generated readme
├── test.html - Main test page
├── test/ - Test files
| ├── test.js - Main test file
| ├── * - Other files and folders for tests go in this folder
├── browser/ - core FuncUnit files
├── doc/ - Documentation source
| ├── guides/ - Guide documentation files
├── node_modules/ - Node dependency installation folder
├── site/ - Files hosted via gh-pages in github
Generally, speaking, the most important files are:
the main module - funcunit.js
the main test module - test/test.js
the test page - test.html
When fixing a bug or making a feature, we'll add a test in the main test module
and update code in the main module and verify the tests are passing by running
the test page.
Once you've figured out where you need to make changes, you'll want to complete the following steps
to make those changes and create a pull request so we can include your code in future releases:
Create a new feature branch. For example, git checkout -b html5-fix.
Make some changes to the code and tests.
Run tests npm test and make sure they pass in all browsers.
Update documentation if necessary.
Push your changes to your remote branch. For example, git push origin html5-fix.
Submit a pull request! Navigate to Pull Requests and click the 'New Pull Request' button. Fill in some
details about your potential patch including a meaningful title. When finished, press "Send pull request". The core team will be notified about your submission and let you know of any problems or targeted release date.
If you enjoy making these kinds of fixes, and want to directly influence CanJS's direction,
consider joining our Core team.
This should produce a static site in your funcunit folder. Open funcunit/index.html
and you should see the site. You might want to use http-server to start
a simple static file server.
Improve the theme's design and styles
The FuncUnit theme is in funcunit/site/theme
Publish the documentation
Once the docs look right locally, commit your changes, then run:
npm run document:publish
The publish-docs.js script will generate the documentation again and push out the gh-pages branch.
Writing API documentation
Our documentation is modeled off of jQuery's. Please read
their guidelines. Also read our
[guides/api].
Generally speaking there are three parts to every documentation page:
Its description
Its signatures
The body (typically "Use" section)
Description
The description section should be a one or two sentence explanation of what this
piece of documentation does from a user centric view. Descriptions are a quick summary
of the why and the what. It should take on an
active voice. For example, [can-component]'s description:
Create a custom element that can be used to manage widgets or application logic.
Notice that it uses "Create" not "Creates".
Signatures
Signatures are the what and the how. They should include all or most of the following:
What the signature does, if different from the description, especially if there are
multiple signatures.
High level details on how the code works.
A simple example showing how to use the code.
[can-compute]'s first signature is a good example of this. First, it explains
what that signature does:
Create a compute that derives its value from other observables.
Then it briefly explains how the code works:
Uses can-observation to call the getterSetter and track observables.
Finally, it provides minimal sample code:
var age = compute(32);
var nameAndAge = compute(function(){
return "Matthew - " + age();
});
nameAndAge() // -> "Matthew - 32"
age(33);
nameAndAge() // -> "Matthew - 33"
Not all signatures need to hit all three points. For example [can-event/batch/batch]'s
signature simply adds a bit more depth to the purpose of [can-event/batch/batch]
and then details how the code works. How to use the code is
left for the body section as importing the module is not necessary to show.
Signature titles should follow jQuery's conventions:
Static methods like: TypeAlias.method()
Prototype methods like: typeAlias.method()
Spaces in between arguments: typeAlias.method( arg1, arg2 )
Brackets around optional args: typeAlias.method( arg1 [, arg2 ], arg3 ) or
typeAlias.method( arg1 [, arg2 ][, arg3 ] )
Make sure to fully document the a signature's parameters and return
value. There's a lot of flexibility in documenting the type expression of
a return value or parameters and the name expression of
parameters.
Parameter and descriptions should start with a Capital and end with a period like:
@param {Type} name Indicates that something should happen.
body
Most body sections start with an ## Use. They should be a mini guide on
how to use that piece of code. Modules should have long bodies that span
multiple topics. For example [can-component]'s body has examples and
information about nearly all of its sub-functions. However
[can-component.prototype.tag can-component.prototype.tag] doesn't have a
use section because it's covered in [can-component].
structuring documentation
Group names (like prototype) should be lower case.
Types should be capitalized {String} except when they are describing a function [can-fixture.requestHandler].
Releases - Maintaining FuncUnit
Making a release
For individual modules
FuncUnit has the same structure as all CanJS individual modules which allows making releases through npm scripts.
All versions should follow the Semantic Versioning guidelines in the form of MAJOR.MINOR.PATCH for
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.
To make a release we have to make sure to be on the master branch and the latest upstream changes and reinstall the latest version of all Node modules:
Overview
FuncUnit is managed by the DoneJS Contributors Team. All contributions from all types of contributors are welcome. Contributing to an Open Source project can be an intimidating experience. We're committed to making the experience as pleasant and rewarding as possible. We're happy to setup a pairing session to show you how to fix a bug or write a feature.
If you have any questions, you can always reach us on Slack.
Report a bug
FuncUnit uses Github Issues to track bugs.
When creating an issue, it's very helpful to include:
Also, please search for previous tickets. If there's something similar, add to that, or give it a
+1
.Finally, if there are any questions, reach out to us on the Bitovi forums or talk to us on Slack.
Priority, Tags, and Complexity
The core team reviews issues and assigns them a
P0
toP4
tag corresponding to the following priorities:P0
- An issue that will preempt any other issues currently being worked on.P1
- A critical feature or bug that needs to be fixed to keep CanJS's high degree of quality.P2
- A feature or bug that is less likely to be encountered, but something we intend to get to.P3
- A nice to have. The OS team might get to it, but it's helpful if the community assists.P4
- A nice to have that the OS team will accept, but will be unlikely to prioritize any effort towards.There are several ways to influence these priorities:
+1
the issue.Also, the core team will often include a complexity indicator in the title that looks like
~NUMBER
. This is a fibonacci number.~1
means its an extremely simple task.~8
is about a half day task.~34
might take a week of experimentation.Suggest a feature
FuncUnit uses Github Issues to track feature requests.
When creating an feature issue, it's very helpful to include:
Here are some examples of well-written feature requests:
Also, please search for previous feature requests. If there's something similar, add to that, or give it a
+1
.Finally, if there are any questions, reach out to us on the Bitovi forums or talk to us on Slack.
Priority, Tags, and Complexity
The core team reviews issues and assigns them a
P0
toP4
tag corresponding to the following priorities:P0
- An issue that will preempt any other issues currently being worked on.P1
- A critical feature or bug that needs to be fixed to keep CanJS's high degree of quality.P2
- A feature or bug that is less likely to be encountered, but something we intend to get to.P3
- A nice to have. The OS team might get to it, but it's helpful if the community assists.P4
- A nice to have that the OS team will accept, but will be unlikely to prioritize any effort towards.There are several ways to influence these priorities:
+1
the issue.Also, the core team will often include a complexity indicator in the title that looks like
~NUMBER
. This is a fibonacci number.~1
means its an extremely simple task.~8
is about a half day task.~34
might take a week of experimentation.Code changes
Contributing to any Open Source project can be intimidating. All contributions from all types of contributors are welcome. We're committed to making the experience as pleasant and rewarding as possible. We're happy to setup a pairing session to show you how to fix a bug or write a feature.
If you have any questions, you can always reach us on Slack.
Setting up your development environment.
Developing FuncUnit requires:
Getting github account and client
Signup for a https://github.com/ account.
There are a variety of ways to get a git command line client connected to your GitHub account. Fortunately, GitHub has great documentation on how to Setup Git.
If you already have
git
installed, make sure you've setup your ssh keys.Get NodeJS
Download Node.js version 4 or later at https://nodejs.org. You can verify node is working at its version with:
Get Firefox
Download the Firefox browser here. Make sure it gets installed into the default location for your operating system.
Firefox is used to run each repository's tests.
Getting the code and verify it is working
Once your environment is setup, you should be able to clone the repository you want to change, install its dependencies, and verify you've setup your development environment correctly.
1. Fork the repository you are working from by clicking the
fork
button.2. Clone the your forked version of the repository.
For example, if your username is
justinbmeyer
, and you forkedfuncunit
:Before the next step, make sure you move into your project's directory. For example:
3. Install npm dependencies with:
4. Make sure Firefox is closed and run the test suite with:
If every test passed, congrats! You have everything you need to change code and send it back to us.
File organization and responsibilities
Understanding the file structure can help you figure out what code needs to be changed.
The following details the directory structure of FuncUnit:
Generally, speaking, the most important files are:
funcunit.js
test/test.js
test.html
When fixing a bug or making a feature, we'll add a test in the main test module and update code in the main module and verify the tests are passing by running the test page.
Where possible, FuncUnit code is:
Make your changes
Once you've figured out where you need to make changes, you'll want to complete the following steps to make those changes and create a pull request so we can include your code in future releases:
git checkout -b html5-fix
.npm test
and make sure they pass in all browsers.git push origin html5-fix
.If you enjoy making these kinds of fixes, and want to directly influence CanJS's direction, consider joining our Core team.
Documentation improvements
The FuncUnit site is generated with DocumentJS. Its content is hosted using Github pages publishing the bitovi/funcunit#gh-pages repo.
DocumentJS reads JavaScript comments and markdown files within the
funcunit
.The guides content for the site is within the
funcunit/doc
folder.Generate the documentation locally
To generate the CanJS site:
Clone https://github.com/bitovi/funcunit.git
Install dependencies:
Run
documentjs
:This should produce a static site in your
funcunit
folder. Openfuncunit/index.html
and you should see the site. You might want to usehttp-server
to start a simple static file server.Improve the theme's design and styles
The FuncUnit theme is in
funcunit/site/theme
Publish the documentation
Once the docs look right locally, commit your changes, then run:
The
publish-docs.js
script will generate the documentation again and push out thegh-pages
branch.Writing API documentation
Our documentation is modeled off of jQuery's. Please read their guidelines. Also read our [guides/api].
Generally speaking there are three parts to every documentation page:
Description
The description section should be a one or two sentence explanation of what this piece of documentation does from a user centric view. Descriptions are a quick summary of the why and the what. It should take on an active voice. For example, [can-component]'s description:
Notice that it uses "Create" not "Creates".
Signatures
Signatures are the what and the how. They should include all or most of the following:
[can-compute]'s first signature is a good example of this. First, it explains what that signature does:
Then it briefly explains how the code works:
Finally, it provides minimal sample code:
Not all signatures need to hit all three points. For example [can-event/batch/batch]'s signature simply adds a bit more depth to the purpose of [can-event/batch/batch] and then details how the code works. How to use the code is left for the
body
section as importing the module is not necessary to show.Signature titles should follow jQuery's conventions:
TypeAlias.method()
typeAlias.method()
typeAlias.method( arg1, arg2 )
typeAlias.method( arg1 [, arg2 ], arg3 )
ortypeAlias.method( arg1 [, arg2 ][, arg3 ] )
Make sure to fully document the a signature's parameters and return value. There's a lot of flexibility in documenting the type expression of a return value or parameters and the name expression of parameters.
Capital
and end with a period like:@param {Type} name Indicates that something should happen.
body
Most body sections start with an
## Use
. They should be a mini guide on how to use that piece of code. Modules should have long bodies that span multiple topics. For example [can-component]'s body has examples and information about nearly all of its sub-functions. However [can-component.prototype.tag can-component.prototype.tag] doesn't have a use section because it's covered in [can-component].structuring documentation
prototype
) should be lower case.{String}
except when they are describing a function [can-fixture.requestHandler].Releases - Maintaining FuncUnit
Making a release
For individual modules
FuncUnit has the same structure as all CanJS individual modules which allows making releases through npm scripts. All versions should follow the Semantic Versioning guidelines in the form of
MAJOR.MINOR.PATCH
forMAJOR
version when you make incompatible API changes,MINOR
version when you add functionality in a backwards-compatible manner, andPATCH
version when you make backwards-compatible bug fixes.To make a release we have to make sure to be on the
master
branch and the latest upstream changes and reinstall the latest version of all Node modules:Now we can run
npm run release:<versiontype>
. For example, to make aPATCH
release:This will run the tests, build, bump the version number accordingly and publish the module to npm.
Continuous integration
Travis
All repositories automatically run their tests in Travis CI using the
npm test
command (browser tests use Firefox as their target browser).