Welcome to our ever-growing community 
!
Ravada is an open-source project that allows users to connect to a virtual desktop. It is a VDI broker.
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. It's people like you that make it such a great tool.
- 1 See what’s going on
- 2 Assistance
- 2.1 Live Support
- 2.2 Discussions
- 3 Feature Requests
- 4 Submitting
- 4.1 How to Submit an Issue or Bugs
- 4.1.1 Check for Past Issues or Bugs
- 4.1.2 Try to Reproduce It!
- 4.1.3 Isolate the Problem
- 4.1.4 Information Needed for the Report
- 4.1.5 Submit an Issue
- 4.2 How to Create a Pull Request (PR)
- 4.2.1 Create a Fork
- 4.2.1.1 Keep updated your Fork
- 4.2.2 Create a Branch and Naming it
- 4.2.3 Make Changes
- 4.2.4 Commit Your Changes
- 4.2.4.1 Rules to Follow
- 4.2.4.2 Commit Format
- 4.2.4.2.1 Header: Writing a
type - 4.2.4.2.2 Header: Writing the
(optional scope) - 4.2.4.2.3 Header: Writing a
description - 4.2.4.2.4 Header Lenght
- 4.2.4.2.5 Writing the
optional body - 4.2.4.2.6 Writing the
optional footer
- 4.2.4.2.1 Header: Writing a
- 4.2.4.3 Commit Examples
- 4.2.5 Push your Changes
- 4.2.6 Create a Pull Request
- 4.2.6.1 How to Write a Title for a Pull Request
- 4.2.6.2 Before Send a Pull Request
- 4.2.6.3 How We Check your Submission
- 4.2.6.3.1 Status Check
- 4.2.6.3.2 App/Bots List
- 4.2.7 How to proceed with suggestions
- 4.2.1 Create a Fork
- 4.1 How to Submit an Issue or Bugs
- 5 What to do next?
- 6 Coding Rules
1. See what's going on! 🔝
If you want to know all the issues we're dealing with right now, take a look at our Issue Dashboard and look for areas in which you can help.
If you want to give us a hand solving issues then great, take a look at our Pull Request Dashboard and check for an open or closed PR. We don’t want to duplicate efforts.
2. Assistance 🔝
You can find us in Telegram, we'll help you as soon as possible.
For general discussion, use the Ravada mailing list.
3. Feature Requests 🔝
If you'd like to make a suggestion, you must first search the existing issues, both opened and closed. Your idea may have already been suggested!
If you like to implement a new feature please submit an Issue with a proposal, so we can be sure it's relevant.
For a major new feature request, open an Issue and outline your proposal so it can be discussed.
For a minor new feature request, you can craft it and directly submit it as a Pull Request, we'll take care of it.
You can request a new feature by submitting an Issue
4. Submitting 🔝
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.
A bug is a demonstrable problem that is caused by the code in the repository. If you're getting a problem when you try to install, there is a good chance that your server is not configured properly. See the troubleshooting guide for help. Good bug reports are extremely helpful, here are steps to follow to build a good one:
Before submitting the issue please check the Issue Tracker, 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.
Try to reproduce this issue/bug using the latest master branch in the repository Check it here.
Ideally, create a reduced test case. We prefer bug reports with small, portable test cases.
We require the following information:
⚠️ Observed Results: A brief description of the problem.- 🔎 What steps will reproduce the issue?: If suitable, including the steps required to reproduce the bug.
- 💥 Expected Results: What did you expect to happen?
Having all data at hand, file the new issue by filling out our Issue form.
— That's it! 🎉
4.2 How to Create a Pull Request (PR) 🔝
Before submitting a Pull Request, check for an open or closed PR that relates to your submission. We don't want to duplicate efforts.
Fork the repository before making any changes, a fork is a copy of the repository which allows you to freely experiment with changes without affecting the original project.
Go to the top-right corner on GitHub, and click on 
To avoid and also to solve conflicts in your PR, you must update your Fork since other team mates may have already submitted their work.
Following this Gist:
1 - Clone your fork
git clone [email protected]:YOUR-USER-NAME/ravada.git
2 - Add remote upstream
cd path/to/your/fork/
git remote add upstream git://github.com/UPC/ravada.git
3 - Update your fork
git fetch upstream
git pull upstream master
📝 Note: You can pull from any branch of the remote repo.
The project is organized according to the branch model Git Flow. 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.
❗ Branch Name Format: feature/issue_number-my-killer-feature.
🚫 Important: Do not commit to our default develop branch. Name it anything except master, develop, release-, or hotfix-. We'll use 1-created-branch an example.
Make your changes in your newly created branch.
git checkout -b feature/1-created-branch master
Follow this guide about running Ravada in development mode.
If you change a translation or language file make sure you follow this small guide.
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.
For commits, we follow the Conventional Commit. 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.
Each commit message consists of a header, a body, and a footer. Each commit must be for a reason, and we should have an issue for that, so we decided to add the issue number in the footer.
The header has a special format that includes a type, a scope, and a description:
The commit message should be structured as follows:
type(optional scope): description
<blank line>
optional body
<blank line>
footer #issueCommits must be prefixed with a type, which consists of a verb, feat, fix, build, followed by a colon and space.
Your options:
- build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm).
- ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs).
- docs: Documentation only changes.
- feat: A new feature.
- fix: A bug fix.
- perf: A code change that improves performance.
- refactor: A code change that neither fixes a bug or adds a feature.
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
- test: Adding missing tests or correcting existing tests.
Example for
type: 👉feat👈(parser): add ability to parse arrays
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.
Example for a
(optional scope): feat:point_right:(parser):point_left:: add ability to parse arrays
A description must immediately follow the type(optional scope): The description is a short description of the commit.
Important
- About commit character length, keep it concise and don't write more than 50 characters.
- Use the imperative present tense: change, make, add, update, fix, etc; Do not use changed, changes, added, fixes, fixed, etc.
- Don't capitalize the first letter.
- Do not use a dot (.) at the end.
Example for
<description>: feat(parser)::point_right:add ability to parse arrays:point_left:
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.
The body should include the motivation for the change and contrast this with previous behavior.
Example for
optional body:
fix orthography
remove out of date paragraph
fix broken linksThe <optional footer> should contain a closing reference to an issue if any.
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.
Example for
optional footer: :point_right:Closes #123:point_left:
💩 Bad
docs(readme): fix orthography, remove out of date paragraph and fix broken links👍 Good
docs(readme): document design improvement change content
fix orthography
remove out of date paragraph
fix broken linksPushing 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.
After working on your changes you need to Push it (upload) your newly created branch to GitHub
git push origin feature/1-created-branch
Then you'll need to run:
git push --set-upstream-to origin feature/1-created-branch
Pull requests or PR are proposed changes to a repository submitted by a user and accepted or rejected by a repository's collaborators.
After all the work being pushed to the newly created branch, In GitHub, send a pull request to our repository.
Pull Request should be named in reference to the main fix or feature you provide; minor information can be added to the description.
📏 Title Length: Keep it concise and don't write more than 50 characters in the title.
🚧 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 will set its status to error.
Example for
Titles for work in progress (WIP):👉WIP Added a Table of Content for the Contributing Guideline Document.👈
✅ 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.
Example for
Titles for Finalized Work:👉Added a Table of Content for the Contributing Guideline Document.👈
1 - Pull Request Description: Write a description about the changes, we provide a template for Pull Request descriptions. When you're creating a Pull Request it'll be shown automatically. Just fill it out and you're done.
2 - Choose the right label: Look at the list of available labels.
3 - Smash that button! Press that Create Pull Request button and you're done.
— That's it! 🎉
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.
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:
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.
WIP: Maintainers: Required / Contributors: Required
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.
AccessLint: Maintainers: Required / Contributors: Required
GPG: After installation, this app checks all commits of new (or newly updated) pull requests for valid GPG signatures according to the GitHub API.
GPG: Maintainers: Required / Contributors: Optional
commitlint: Runs commitlint against all commits of new or edited pull requests and sets an appropriate status check.
commitlint: Maintainers: Required / Contributors: Required
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.
DCO: Maintainers: Required / Contributors: Optional
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.
DEP: Maintainers: Required / Contributors: Required
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.
ci/circleci build: Maintainers: Required / Contributors: Required
continuous-integration/travis-ci/push(and pr): An automatic construction of the requested changes is carried out and the tests are executed automatically.
continuous-integration/travis-ci/push(and pr): Maintainers: Required / Contributors: Required
If we suggest changes then:
-
Make the required updates.
-
Re-run the test suites to ensure tests are still passing.
-
Rebase your branch and force push to your GitHub repository (this will update your Pull Request):
git rebase develop -i git push -f
5. What to do next? 🔝
After your pull request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:
-
Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:
git push origin --delete feature/1-created-branch
-
Check out the master branch:
git checkout master -f
-
Delete the local branch:
git branch -D feature/1-created-branch
-
Update master with the latest upstream version:
git pull --ff upstream master
6. Coding Rules 🔝
To ensure consistency throughout the source code, keep these rules in mind as you are working:
- All features or bug fixes must be tested by one or more specs (unit-tests). See this documentation about testing the project.
- All methods must be documented.
- Code Style: see our
editor configuration
guidelines so your code gets along with old code. A recurrent problem for newcommers
is to submit code automatically cleaned by the editor. Usually, removed end of line
spaces or spaces converted to tabs.
Please make sure you don't do that. Run
git diffbefore commit to see what you are exactly contributing. - We recommend that you install a local development server on your computer, rather than testing your code directly on the production server. This means you can test your code directly on your own computer, making development faster and without the risk of exposing sensitive information to the public.
