Contributing to Kitura
We love contributions to the Kitura project and request you follow the guidelines below. If you have any questions, or need any help, contact us on Slack.
- Getting Started
- Pull Requests
- Coding Style
- Contributor License Agreement
- Asking Questions
- Reporting issues
- Additional Resources
First time contributing? We have created the label "good first issue" to help new members of the community get involved with Kitura quickly and effectively. These issues include documentation changes, test cases, minor bug fixes, logging, renaming and refactoring.
To get started, you will need to open a Terminal and:
Fork this repo and clone it onto your machine.
$ git clone https://github.com/YOUR_GITHUB_ID/Kitura
If there aren't any tagged issues, post in Slack and the team would be happy to help you get started.
Tip: If you are on macOS, Xcode can be a great way to work on Kitura. You can download the latest Xcode here. Navigate to the root of the Kitura project you cloned and then type the following command:
$ swift package generate-xcodeproj
This will generate an Xcode Project, open the .xcodeproj file with:
$ open *.xcodeproj
Note: Xcode is macOS only, Linux users will need to use a different editor.
All source code submitted requires an Apache License header at the top of the file. A Github Gist of this text can be found here, just copy and paste it at the top of any new files you're submitting.
Ensure all tests pass with your changes by running
swift test. If there is any new functionality introduced by your changes, new test case(s) may be required. If you need any help writing tests, contact us on Slack.
If the tests all pass, open a Pull Request following the guidelines below.
Note: Before opening a Pull Request, please run the tests using
swift test and check they all pass.
Kitura is a cross platform web framework that uses Continuous Integration. You may see mentions of Travis CI in your PR and its comments. Travis is an external service we use that is automatically called on every PR, and runs the test cases on macOS and Linux to ensure every code change is cross plaform compatible.
To open a new Pull Request, the GitHub website provides the simplest experience for new users. Go to your fork of the repo and click the New pull request button. You will be presented with a page featuring base fork: and base:, then an arrow, and then head fork: compare:. Make sure compare: has your branch with your changes selected and base: has master selected. When you are ready to open the PR, click the green button at the top called Create pull request.
If this is your first PR, a bot will comment with a link to the CLA which must be signed before we can merge your changes into master.
When opening a PR, please:
- Create minimal differences and do not reformat the code. If you feel the codes structure needs changing, open a separate PR.
- Check for unnecessary white space using
git diff --checkbefore you commit your code.
- Ensure you follow the coding standards for the Kitura project, linked here.
Contributions should follow the established coding style and conventions for this project, which are loosely based on GitHub's Swift Style Guide. When opening a PR, try to follow the coding style of the file you're working on, and comment code that is particularly complex. Kitura contributions should follow the Kitura Coding Standards
This also ensures that Swift Lint works on the project.
Contributor License Agreement
In order for us to merge any of your changes into Kitura, you need to sign the Contributor License Agreement. When you open up a Pull Request for the first time, a bot will comment with a link to the CLA.
If you have any questions, message us on Slack. Comment on existing issues, or raise new ones if you discover something.