forked from gnss-sdr/gnss-sdr
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
as suggested at https://github.com/blog/1184-contributing-guidelines
- Loading branch information
1 parent
32e4d22
commit 50b6ae1
Showing
1 changed file
with
176 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,176 @@ | ||
# Contributing to GNSS-SDR | ||
|
||
:+1::tada: Thanks for taking the time to contribute! :tada::+1: | ||
|
||
Third-party contributions are essential for keeping GNSS-SDR | ||
continuously improving. We simply cannot access the huge number of | ||
platforms and myriad configurations for running GNSS-SDR. We want to | ||
keep it as easy as possible to contribute changes that get things | ||
working in your environment. There are a few guidelines that we need | ||
contributors to follow so that we can have a chance of keeping on top of | ||
things. | ||
|
||
The following is a set of guidelines for contributing to GNSS-SDR, which | ||
is hosted in the [GNSS-SDR Organization](https://github.com/gnss-sdr) on | ||
GitHub. These are just guidelines, not rules. Use your best judgment, | ||
and feel free to propose changes to this document in a [pull | ||
request](#how-to-submit-a-pull-request). | ||
|
||
## Code of Conduct | ||
|
||
This project adheres to the Contributor Covenant [code of | ||
conduct](CODE_OF_CONDUCT.md). By participating, you are expected to | ||
uphold this code. Please report unacceptable behavior. | ||
|
||
## Reporting an issue | ||
|
||
Have you found a bug in the code which is not in the [list of known | ||
bugs](https://github.com/gnss-sdr/gnss-sdr/issues)? Do you have a | ||
suggestion for improvement? Then by all means please [submit a new | ||
issue](https://github.com/gnss-sdr/gnss-sdr/issues/new), and do not | ||
hesitate to comment on existing [open | ||
issues](https://github.com/gnss-sdr/gnss-sdr/issues). | ||
|
||
When filling a new issue, please remember to: | ||
|
||
* **Use a clear and descriptive title** for the issue to identify the | ||
problem. | ||
|
||
* **Describe the exact steps which reproduce the problem** in as many | ||
details as possible. For example, start by describing your computing | ||
platform (Operating System and version, how did you installed GNSS-SDR | ||
and its dependencies, what file or front-end are you using as a signal | ||
source, etc.). You can also include the configuration file you are | ||
using, or a dump of the terminal output you are getting. The more | ||
information you provide, the more chances to get useful answers. | ||
|
||
* **Please be patient**. This organization is run on a volunteer basis, | ||
so it can take some time to the Developer Team to reach your issue. | ||
They will do their best to fix it as soon as possible. | ||
|
||
* If you opened an issue that is now solved, it is a good practice to | ||
**close it**. | ||
|
||
The list of [open issues](https://github.com/gnss-sdr/gnss-sdr/issues) | ||
can be a good starting point and a source of ideas if you are looking to | ||
contribute to the source code. | ||
|
||
|
||
## Contributing to the source code | ||
|
||
### Preliminaries | ||
|
||
1. If you still have not done so, [create your personal account on | ||
GitHub](https://github.com/join). | ||
|
||
2. [Fork GNSS-SDR from | ||
GitHub](https://github.com/gnss-sdr/gnss-sdr/fork). This will copy the | ||
whole gnss-sdr repository to your personal account. | ||
|
||
3. Then, go to your favourite working folder in your computer and | ||
clone your forked repository by typing (replacing ```YOUR_USERNAME``` by | ||
the actual username of your GitHub account): | ||
|
||
$ git clone https://github.com/YOUR_USERNAME/gnss-sdr | ||
|
||
4. Your forked repository https://github.com/YOUR_USERNAME/gnss-sdr | ||
will receive the default name of `origin`. You can also add the original | ||
gnss-sdr repository, which is usually called `upstream`: | ||
|
||
$ cd gnss-sdr | ||
$ git remote add upstream https://github.com/gnss-sdr/gnss-sdr.git | ||
|
||
To verify the new upstream repository you have specified for your fork, | ||
type `git remote -v`. You should see the URL for your fork as `origin`, | ||
and the URL for the original repository as `upstream`: | ||
|
||
``` | ||
$ git remote -v | ||
origin https://github.com/YOUR_USERNAME/gnss-sdr.git (fetch) | ||
origin https://github.com/YOUR_USERNAME/gnss-sdr.git (push) | ||
upstream https://github.com/gnss-sdr/gnss-sdr.git (fetch) | ||
upstream https://github.com/gnss-sdr/gnss-sdr.git (push) | ||
``` | ||
|
||
### Start working on your contribution | ||
|
||
Checkout the `next` branch of the git repository in order to get | ||
synchronized with the latest development code: | ||
|
||
``` | ||
$ git checkout next | ||
$ git pull upstream next | ||
``` | ||
|
||
When start working in a new improvement, please **always** branch off | ||
from `next`. Open a new branch and start working on it: | ||
|
||
``` | ||
$ git checkout -b my_feature | ||
``` | ||
|
||
Now you can do changes, add files, do commits (please take a look at | ||
[how to write good commit | ||
messages](https://chris.beams.io/posts/git-commit/)!) and push them to | ||
your repository: | ||
|
||
``` | ||
$ git push origin my_feature | ||
``` | ||
|
||
If there have been new pushes to the `next` branch of the `upstream` | ||
repository since the last time you pulled from it, you might want to put | ||
your commits on top of them (this is mandatory for pull requests): | ||
|
||
``` | ||
$ git pull --rebase upstream next | ||
``` | ||
|
||
### How to submit a pull request | ||
|
||
When the contribution is ready, you can [submit a pull | ||
request](https://github.com/gnss-sdr/gnss-sdr/compare/). Head to your | ||
GitHub repository, switch to your `my_feature` branch, and click the | ||
_**Pull Request**_ button, which will do all the work for you. Code | ||
comparison must be always to the `next` branch. | ||
|
||
Once a pull request is sent, the Developer Team can review the set of | ||
changes, discuss potential modifications, and even push follow-up | ||
commits if necessary. | ||
|
||
Some things that will increase the chance that your pull request is | ||
accepted: | ||
|
||
* Avoid platform-dependent code. If your code require external | ||
dependencies, they must be available as packages in [Debian OldStable](https://wiki.debian.org/DebianOldStable). | ||
* Write tests. | ||
* Follow our [coding style guide](http://gnss-sdr.org/coding-style/). | ||
* Write a descriptive and detailed summary. Please consider that | ||
reviewing pull requests is hard, so include as much information as | ||
possible to make your pull request's intent clear. | ||
|
||
For more details about Git usage, please check out [our | ||
tutorial](http://gnss-sdr.org/docs/tutorials/using-git/). | ||
|
||
|
||
## Contributing to the website | ||
|
||
The content of http://gnss-sdr.org lives in a GitHub repository at | ||
https://github.com/gnss-sdr/geniuss-place | ||
|
||
You can fork that repository, reproduce the entire website on your | ||
computer using [Jekyll](https://jekyllrb.com/), do changes and submit | ||
pull requests, just as explained above. For more details, please check | ||
out [how to contribute](http://gnss-sdr.org/contribute/). | ||
|
||
Last but not the least, you can leave your comments on the website. | ||
|
||
|
||
------ | ||
|
||
|
||
|
||
![GeNiuSS | ||
contributes](http://gnss-sdr.org/assets/images/geniuss-contribute.png) | ||
|
||
Thanks for your contribution to GNSS-SDR! |