mirror of https://github.com/gnss-sdr/gnss-sdr
208 lines
8.2 KiB
Markdown
208 lines
8.2 KiB
Markdown
# Contributing to GNSS-SDR
|
|
|
|
<!-- prettier-ignore-start -->
|
|
[comment]: # (
|
|
SPDX-License-Identifier: GPL-3.0-or-later
|
|
)
|
|
|
|
[comment]: # (
|
|
SPDX-FileCopyrightText: 2011-2021 Carles Fernandez-Prades <carles.fernandez@cttc.es>
|
|
)
|
|
<!-- prettier-ignore-end -->
|
|
|
|
:+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 favorite 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 referred to as `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 do not forget to
|
|
[sign your commits](https://gnss-sdr.org/docs/tutorials/using-git/#sign-your-commits)
|
|
if you plan to submit your code to the upstream repository in a pull-request,
|
|
see below) 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
|
|
|
|
Any code contributions going into GNSS-SDR will become part of a GPL-licensed,
|
|
open source repository. It is therefore imperative that code submissions belong
|
|
to the authors, and that submitters have the authority to merge that code into
|
|
the public GNSS-SDR codebase.
|
|
|
|
For that purpose, we use the
|
|
[Developer's Certificate of Origin](https://github.com/gnss-sdr/gnss-sdr/blob/next/.github/DCO.txt).
|
|
It is the same document used by other projects. Signing the DCO states that
|
|
there are no legal reasons to not merge your code.
|
|
|
|
To sign the DCO, suffix your git commits with a `Signed-off-by:` line. When
|
|
using the command line, you can use `git commit -s` to automatically add this
|
|
line. If there were multiple authors of the code, or other types of
|
|
stakeholders, make sure that all are listed, each with a separate
|
|
`Signed-off-by:` line. See
|
|
[how to sign commits](https://gnss-sdr.org/docs/tutorials/using-git/#sign-your-commits)
|
|
for details on how to tell Git to sign commits by default.
|
|
|
|
Before submitting your code, please be sure to
|
|
[apply clang-format](https://gnss-sdr.org/coding-style/#use-tools-for-automated-code-formatting).
|
|
|
|
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:
|
|
|
|
- Your commits must be signed.
|
|
- 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](https://gnss-sdr.org/coding-style/).
|
|
Specifically, please make sure that you have applied
|
|
[clang-format](https://clang.llvm.org/docs/ClangFormat.html) and
|
|
[clang-tidy](https://clang.llvm.org/extra/clang-tidy/) to your changes before
|
|
you do your pull request. Please check the
|
|
[final recommendations](https://gnss-sdr.org/coding-style/#final-recommendations)
|
|
for guidelines on how to apply those tools.
|
|
- 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](https://gnss-sdr.org/docs/tutorials/using-git/).
|
|
|
|
## Contributing to the website
|
|
|
|
The content of https://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](https://gnss-sdr.org/contribute/).
|
|
|
|
Last but not the least, you can leave your comments on the website.
|
|
|
|
---
|
|
|
|
|
|
|
|
Thanks for your contribution to GNSS-SDR!
|