Contributing

Contributing to GNSS-SDR

Found a bug in the code? Interested in adding a new feature or fixing a known bug? Then by all means submit an issue or pull request. If this is your first pull request, it may be helpful to read up on the GitHub Flow first. If you need a quick introduction to Git and its parlance (concepts such as repository, commit, push, pull-request, etc.), check our Git tutorial. This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code.

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. 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.

The basic setup steps for a contribution to the source code are the following:

  1. If you still have not done so, create your personal account on GitHub.

  2. Fork the GNSS-SDR source code repository from GitHub. This will copy the whole source code repository into your personal account.

    Fork GNSS-SDR from GitHub

  3. Then, clone your forked repository into your local machine, checkout the next branch, branch off from it, and start working on the source code.

  4. Be sure to sign your commits to indicate that you fulfill the Developer’s Certificate of Origin.

  5. When your contribution is ready, head your browser to your GitHub repository, switch to the branch where your contributions are, and click the Pull Request button.

More details are available in the CONTRIBUTING.md file.

Before start working in GNSS-SDR source code, especially if you want to contribute your changes back to the upstream repository, you may be interested in having a look at our coding style guide. The usage of clang-format for automated code formatting is highly recommended.

Contributing to this website

Found a typo on this website? Interested in giving your thoughts on existing pages, adding a post, tutorial, new feature, or enhancement?

This website itself lives in a GitHub repository. You can contribute in several ways:

  • Commenting (through your Google, Facebook, or Twitter account, or just open a new profile at Disqus) in the boxes such as the one at the bottom of this page. Moderation will be applied only in cases of flagrant off-topic or unappropriated style (see our code of conduct).

  • Sharing the content on your favorite social network.

  • Checking existing open issues or submitting a new one.

  • Forking this web, cloning the repository, branching off from the main branch, working on the changes in your own repository, and making a pull request.

    Fork this website from GitHub

How to run this website locally

The required software can be installed through RubyGems, which is probably already installed in your system. If this is not the case, please check how to install Ruby.

Install Bundler, a tool for managing the required dependencies:

$ gem install bundler

Clone your forked repository of this website and install the required dependencies (replacing YOUR_USERNAME by your actual GitHub user name):

$ git clone https://github.com/YOUR_USERNAME/geniuss-place/
$ cd geniuss-place
$ bundle install

After all gems are installed, the following command will deploy the website and run a local server at http://127.0.0.1:4000/

$ bundle exec jekyll serve -w --config _config.yml,_config.dev.yml

You should see something as:

Configuration file: _config.yml
Configuration file: _config.dev.yml
            Source: /path_to_cloned_repo/geniuss-place
       Destination: /path_to_cloned_repo/geniuss-place/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
       Jekyll Feed: Generating feed for posts      
                    done in 4.017 seconds.
 Auto-regeneration: enabled for '/path_to_cloned_repo/geniuss-place'
    Server address: http://127.0.0.1:4000/
  Server running... press ctrl-c to stop.

Just point your browser to http://127.0.0.1:4000/ in order to enjoy this website without the need for an Internet connection. Some features such as comments might not work.

If you already forked and cloned this repo before, and then have pulled from upstream, be sure to keep your gems updated with the exact required versions by re-running:

$ bundle install

Pro Tip: if you want to modify JavaScript (under assets/js), you will need to install Node.js, cd to the root of your project, and run $ npm install to get all the dependencies. If all went well, then running npm run build:js will compress/concatenate _main.js and all plugin scripts into main.min.js. Thus, upon a change on JavaScript content, run:

$ npm run build:js

in order to update the main.js script and implement the changes on the website.

Note: If you upgraded from a previous version of the website be sure you copied over package.json prior to running npm install.

Note: “master” to “main” transition. In June 2020, GitHub announced it would start to remove references to the term “master” from GitHub services and replacing it with a more neutral term like “main,” a change already adopted by many other communities (see some media reports here and here). Moving to use “main” felt an appropriate way to honor our own code of conduct, so we implemented this change on March 22, 2021. If you cloned or forked this repository before that date, you can update your own repository by doing:

  1. Fetch from the upstream repository: 
    $ git fetch https://github.com/gnss-sdr/geniuss-place/
  2. Checkout the newly fetched main branch and change the HEAD pointer to it: 
    $ git checkout main
$ git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main

    If you only cloned the repository from upstream, then you are good to go.

  3. If you forked from the upstream repo, push the local main branch to your own repo: 
    git push -u origin main
  4. Change the default branch name to “main” on your forked GitHub repository. This is the only step that requires you to leave the Terminal and navigate in your browser to your GitHub repository https://github.com/YOUR_USERNAME/geniuss-place/. From there, click “Settings” “Branches” on the left rail and change the default branch to “main”.
  5. Delete your master branch: 
    $ git push origin --delete master

    Now main is your new default branch, and you are ready to deploy the website on a local server, and to branch-off from it if you are planning to make changes and to submit a Pull Request.

Updated:

Leave a comment

You may also enjoy

Introducing Geniux v24.02

Introducing Geniux v24.02

18 minute read

Geniux v24.02: a GNU/Linux custom distribution for running GNSS-SDR on embedded devices.