Contribute to Restcomm
Try Restcomm Cloud NOW for FREE! Zero download and install required.
All Restcomm docs and downloads are now available at https://www.restcomm.com.
Multiple types of contributions are possible :
- Using it in your product or project and providing feedback.
- Code & Algorithms: Core Projects, Incubator projects, Frameworks
- Use cases, feature requests: Roadmap influence
- Community Support, bug fixes, forum posts: Help to be helped
- Documentation: Everyone needs good docs, Code is a moving targed.
- Testing (Perf, load, security, unit tests, interop, ...) / CI
Here is specific types of contributions that requires a little more details if you want to get involved
- Fixing Bugs : See https://help.github.com/articles/closing-issues-via-commit-messages
- Reporting Bugs : To report a bug, if possible, provide a small example that illustrates the bug. You can pattern the test case usually along the lines of ones found in the testsuite. Having a test case handy speeds up the bug fix. Your test case will be included in the project as a test case. open an Issue as defined in the section below so other users can know about the issue and its status. Please attach your test case or bug description with debug log files there.
- Contributing Extensions and enhancements (i.e. support for extension RFCs and drafts that are not covered by Restcomm) or Contributing code snippets and examples or Contributing test cases to be included with the distribution: See Contribution Process below in Section "How to check out, change, review, and commit code". Also open a thread on the mailing list of Restcomm google group to discuss it with the community and Restcomm Team Members.
Your contributions will be acknowledged individually in the code (as a comment) and in the Acknowledgement page.
In order to become a contributor with write access to the code, you will need to have demonstrated an understanding of the codebase and testsuite by participating in the design discussions and submitting patches for bugs/enchancements before we will grant developer access.
Contributing to Restcomm requires you to accept the TeleStax Contributor Agreement (bottom of the page).
Restcomm projects use Git, a distributed version control system. What this means is that, even though this page hosts a central repository, there can be many clone repositories with changes of their own, and then some of those can be merged back into the main repository.
- The great part is that you can start contributing and create our own clone without having write access to the Restcomm repository*
This document describes the workflow for checking out code, making clones, reviewing patches, and committing code.
For non-committers, checking out code is simple.
Follow the installing Git instructions. Ubuntu users can simply type:
sudo apt-get install git-core
Configure Git to convert line endings on commit
git config --global core.autocrlf input
To check out the code :
git clone git@github.com:Restcomm/Restcomm-Connect.git
To Build Restcomm from Source, follow those instructions : http://docs.telestax.com/restcomm-mobicents-building-from-source/
The following License Header has to be placed on top of each source code file contributed
/* * TeleStax, Open Source Cloud Communications * Copyright 2011-2017, Telestax Inc and individual contributors * by the @authors tag. * * This program is free software: you can redistribute it and/or modify * under the terms of the GNU Affero General Public License as * published by the Free Software Foundation; either version 3 of * the License, or (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Affero General Public License for more details. * * You should have received a copy of the GNU Affero General Public License * along with this program. If not, see <http://www.gnu.org/licenses/> * */
The model we've chosen for developing Restcomm is the following:
Each contributor creates their own fork of the Restcomm project (you want to contribute to) repository.
This clone is hosted on Github servers, and can be created by clicking *Fork* button from https://github.com/Restcomm/Restcomm-Connect
The contributor then makes a local clone of their GitHub fork, which is stored on their local machine. Instructions for checking it out is https://github.com//Restcomm
The contributor creates a new Issue explaining their contribution at https://github.com/Restcomm/Restcomm-Connect/issues/new
The contributor then creates a new branch into their local clone
git checkout -b feature-branch
Do the changes into their branch for their local branch for the contribution and commit them
git commit -a -m "commit message"
IMPORTANT:Please use the Github integration to use the commit message to tie the commits to the Issue you're working on. More information on that can be found at https://help.github.com/articles/closing-issues-via-commit-messages
IMPORTANT: When your change is pulled into the main Restcomm source, the change description that you entered here will show up as changes in the main Restcomm source, so please use a meaningful description - fixing bug, making changes, etc. are not ok, please instead use something like fixing transform bug caused by NPE, etc. so that it makes sense in the context of Restcomm as a whole, not just your clone.
If you have any new files, make sure to use the following command before committing
git add <file or directory>
Same thing if you want to remove some files
git rm <file or directory>
When a change is ready to be integrated back into the repository, that change is pushed from the developer's local clone to their Github Fork clone.
git push origin feature-branch
To avoid merge soup, please rebase your branch first
If the main repository has evolved since your last push to your clone repository, you will need to bring those changes into your repository as well as potentially merge them.
You need to add a remote via which you will identify the upstream repository:
git remote add upstream git@github.com:Restcomm/Restcomm-Connect.git
Now whenever you want to merge upstream changes into your clone, do the following:
git fetch upstream git merge upstream/master
First pull in all of the latest changes from upstream, apply them to your master branch, then rebase your feature branch against master before merging it into master and pushing it upstream:
git checkout master git fetch upstream git merge upstream/master git checkout awesome-feature git rebase master (fix any conflicts with upstream changes) git push origin feature-branch
Browse to Source -> Changes from the project page for your clone and navigate to the page with details on the branch to be reviewed. By example, https://github.com//Restcomm/tree/development
You will need to paste the URL for this page into the issue you created earlier. Describe the code to be reviewed, its purpose, and paste in the URL for the relevant changeset(s) or branch(es).
The code will be reviewed on the contributor's clone - if any further changes are suggested, a couple of iterations might be needed so the contributor will need to modify the code again, commit, push and comment on the issue.
Once the change is approved, a committer of Restcomm will merge it back into the main repository with the following commands.
git checkout -b feature-branch git pull https://github.com/<contributor_github_account>/Restcomm/ feature-branch git checkout master git merge feature-branch
Even though this may sound complicated, this process makes code reviews easier and allows a lot of people to work on changes in parallel.
In order to avoid merge conflicts, be it with new features or bug fixes, Restcomm takes advantage of maven code formatting plugin. By default, all of our projects trigger this plugin during build. It provides information on code style and violations of certain rules. Example failure may look as follows:
[INFO] Starting audit...
/home/baranowb/Restcomm/git/test/src/main/java/Test.java:46: Line has trailing spaces.
/home/baranowb/Restcomm/git/test/src/main/java/Test.java:47:1: '{' should be on the previous line.
/home/baranowb/Restcomm/git/test/src/main/java/Test.java:50: Line has trailing spaces.
Audit done.Contributor responsibility is to provide us with code, which obeys formatting rules. If source does not pass code style checks, it wont be accepted!
IDEs have native support for formatting. To take advantage of it, you need to import configuration files. Restcomm has projects wide configuration for IDEs. It can be found here: http://grepcode.com/snapshot/repo1.maven.org/maven2/org.mobicents/checkstyle/1.0.0.FINAL/ or in any tagged relase of this artifact.
To import formatter rules into eclipse perform following:
- Window > Preferences > Java > Code Style > Clean Up > 'Import' -> cleanup.xml
- Window > Preferences > Java > Code Style > Formatter > 'Import' -> formatter.xml
Optionally:
- Window > Preferences > Java > Code Style > Code Templates > 'Import' -> templates.xml
The checkstyle plugin is pre-configured in mobicents-parent artifact. To enable it in any subproject which depends on it, you need to add only following lines in *plugins* section of master project pom:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
</plugin>This section covers basic code conventions and practices you should follow to pass review without problems.
- If you want to create new actor class make sure it extends RestcommUntypedActor which is a common UntypedActor with overridden supervisor strategy.
- The best way to define actors Props is to use factory method in companion object
public class MyActor extends RestcommUntypedActor {
public static Props props(final Object params) {
return new Props(new UntypedActorFactory() {
@Override
public Actor create() throws Exception {
return new MyActor(params);
}
});
}
private MyActor(Object params) {
...
}
...
}