From 7988cdbdcb2770eab82fa82ed7d87b7fa2a01d08 Mon Sep 17 00:00:00 2001 From: Vasilis Tsiligiannis Date: Thu, 14 Mar 2019 22:26:48 +0200 Subject: [PATCH] Update contribution and developing guides Signed-off-by: Vasilis Tsiligiannis --- CONTRIBUTING.md | 158 ++++++++++++++++++++++++++++++++++++++- docs/contribute.rst | 128 ------------------------------- docs/developer-guide.rst | 77 +++++++++++++++++++ docs/index.rst | 2 +- 4 files changed, 232 insertions(+), 133 deletions(-) delete mode 100644 docs/contribute.rst create mode 100644 docs/developer-guide.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 01ee5eb..be146f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,157 @@ -# Contributing to SatNOGS Network +# Libre Space Foundation Contribution Guide # -Thank you for your interest in contributing to SatNOGS! +## Table of Contents ## -Please read the `Contribution Guidelines` in [satnogs-network documentation](https://docs.satnogs.org/en/stable/satnogs-network/docs/contribute.html). + * [Introduction](#introduction) + * [Obtain the source code](#obtain-the-source-code) + * [Separate the changes](#separate-the-changes) + * [Quality check of the changes](#quality-check-of-the-changes) + * [Describe the changes](#describe-the-changes) + * [Create a merge request](#create-a-merge-request) + * [Respond to review comments](#respond-to-review-comments) + * [Don’t get discouraged - or impatient](#dont-get-discouraged-or-impatient) + * [Sign your work - the Developer’s Certificate of Origin](#sign-your-work-the-developers-certificate-of-origin) + * [References](#references) -The main repository lives on [Gitlab](https://gitlab.com/librespacefoundation/satnogs/satnogs-network). +## Introduction ## +For a person or company who wishes to submit a change to a Libre Space Foundation project source code, the process can sometimes be daunting if you’re not familiar with “the system”. +This document is a collection of suggestions which can greatly increase the chances of your change being accepted. +It is based on Linux kernel patch submission guidelines. + +## Obtain the source code ## + +All Libre Space Foundation projects code is maintained under Git. +Obtain a copy of the source code using `git clone`. +Development usually takes place under `master` or `dev` branch. + +## Separate the changes ## + +Make changes as small as possible by separating each logical change into a separate commit. +Such commits are also called *atomic*. +Atomic commits must be complete and functional. +Small commits make it easier for someone to review by seeing changes incrementally. +It also makes it easier to roll back changes without affecting other changes. + +For example, if your changes include both bug fixes and a new feature, separate those changes into two or more commits. +On the other hand, if you make a single change to numerous files, group those changes into a single commit. +Thus a single logical change is contained within a single commit. +The point to remember is that each commit should make an easily understood change that can be verified by reviewers. +Each commit should be justifiable on its own merits. + +When creating a merge request from a series of commits, take special care to ensure that the software builds and runs properly after each commit in the series. +Developers using `git bisect` to track down a problem can end up splitting your merge request at any point; they will not thank you if you introduce bugs in the middle. + +If you cannot condense your merge request into a smaller set of commits, then only submit say 15 or so at a time and wait for review and integration. + +Never commit binary files. +Once they are part of Git repository history they cannot be removed. + +## Quality check of the changes ## + +Continuous Integration will check your changes automatically once you create a merge request. +Nevertheless, local quality check should also be done before submitting a merge request. +The checks can include: + * Static code analysis and coverage + * Dynamic code analysis + * Unit testing + * Functional testing + +All quality checks must pass for your changes to be merged. + +## Describe the changes ## + +These are the seven rules of a great Git commit messages: + + * Separate subject from body with a blank line + * Limit the subject line to 50 characters (if possible) + * Capitalize the subject line + * Do not end the subject line with a period + * Use the imperative mood in the subject line + * Wrap the body at 72 characters + * Use the body to explain what and why vs. how + +See [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) by Chris Beams for details. + +Try to solve a single problem per each commit. +If your description ends up too long, that’s an indication that you probably need to split up your commit. +See [Separate the changes](#separate-the-changes). + +Create commit or merge requests descriptions that are self-contained. +This benefits both the maintainers and reviewers. +Always use your real name and e-mail address for committing changes. + +If the commit fixes a reported issue, refer to that bug entry by issue number. +The issue will be closed automatically after merge, if it matches [this regular expression](https://docs.gitlab.com/ce/user/project/issues/automatic_issue_closing.html). + +## Create a merge request ## + +A series of loosely related commits can be submitted as a merge request. +Libre Space Foundation projects follow a [forking workflow](https://docs.gitlab.com/ce/workflow/forking_workflow.html). +Merge requests must not contain other merge requests; re-base your commits if necessary. + +## Respond to review comments ## + +Your merge request will almost certainly get comments from reviewers on ways in which it can be improved. +You must respond to those comments; ignoring reviewers is a good way to get ignored in return. +Be sure to tell the reviewers what changes you are making and to thank them for their time. +Code review is a tiring and time-consuming process, and reviewers sometimes get grumpy. +Even in that case, though, respond politely and address the problems they have pointed out. + +## Don’t get discouraged - or impatient ## + +After you have submitted your merge request, be patient and wait. +Reviewers are busy people and may not get to your merge request right away. +You should receive comments within a week or so. +Wait for a minimum of one week before pinging reviewers - possibly longer during busy times. + +## Sign your work - the Developer’s Certificate of Origin ## + +To improve tracking of who did what, especially with commits that can percolate to their final resting place in Libre Space Foundation projects code-base through several layers of maintainers, we’ve introduced a “sign-off” procedure on commits. + +The sign-off is a simple line at the end of the explanation for the commit, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch. +The rules are pretty simple: + +if you can certify the below: + + Developer’s Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + a. The contribution was created in whole or in part by me and I have + the right to submit it under the open source license indicated in + the LICENSE file; or + b. The contribution is based upon previous work that, to the best of + my knowledge, is covered under an appropriate open source license + and I have the right under that license to submit that work with + modifications, whether created in whole or in part by me, under + the same open source license (unless I am permitted to submit + under a different license), as indicated in the LICENSE file; or + c. The contribution was provided directly to me by some other person + who certified (a), (b) or (c) and I have not modified it. + d. I understand and agree that this project and the contribution are + public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + +then you just add a line saying: + +`Signed-off-by: Random J Developer ` + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +If you are a maintainer, sometimes you need to slightly modify commits order to merge them. +If you stick strictly to rule (c), you should ask the submitter to rediff, but this is a totally counter-productive waste of time and energy. +Rule (b) allows you to adjust the code, but then it is very impolite to change one submitter’s code and make him endorse your bugs. +To solve this problem, it is recommended that you add a line between the last Signed-off-by header and yours, indicating the nature of your changes. +While there is nothing mandatory about this, it seems like prepending the description with your mail and/or name, all enclosed in square brackets, is noticeable enough to make it obvious that you are responsible for last-minute changes. Example: + +``` +Signed-off-by: Random J Developer +[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] +Signed-off-by: Lucky K Maintainer +``` + +## References ## + + * Linux kernel documentation - [Submitting patches: the essential guide to getting your code into the kernel](https://www.kernel.org/doc/html/latest/process/submitting-patches.html) diff --git a/docs/contribute.rst b/docs/contribute.rst deleted file mode 100644 index c73b395..0000000 --- a/docs/contribute.rst +++ /dev/null @@ -1,128 +0,0 @@ -Contribute -========== - -Thank you for your interest in contributing to SatNOGS! There are always bugs to file; bugs to fix in code; improvements to be made to the documentation; and more. - -The below instructions are for software developers who want to work on `satnogs-network code `_. - -Git workflow ------------- -When you want to start contributing, you should :doc:`follow the installation instructions `, then... - -#. (Optional) Set your cloned fork to track upstream changes (changes to the main repository), then fetch and merge changes from the upstream branch:: - - $ git remote add --track master upstream git://gitlab.com/librespacefoundation/satnogs/satnogs-network - $ git fetch upstream - $ git merge upstream/master - -#. Set up a branch for a particular set of changes and switch to it:: - - $ git branch my_branch - $ git checkout my_branch - -#. Commit changes to the code! - -#. Code! - -#. Lint the code:: - - $ flake8 network - - and fix any errors. - -#. Commit changes to the code! - -#. When you're done, figure out how many commits you've made:: - - $ git log - -#. Squash all those commits into a single commit that has a `good git commit message `_. (Example assumes you made 4 commits):: - - $ git rebase -i HEAD~4 - -#. Use the interactive editor that pops up to pick/squash your commits:: - - pick 01d1239 [fix bug 893291] Make it go to 11 - squash 32as32p added the library and made some minor changes - squash 30ame3z build the template - squash 91pcla8 ugh fix a semicolon bug in that last commit - -#. Push your changes to your fork:: - - $ git push origin my_branch - -#. Issue a pull request on Gitlab to the dev branch (not master) - -#. Wait to hear from one of the core developers. You can find us on irc or matrix in channel satnogs if you wish to discuss your MR in real time. - -If you're asked to change your commit message, you can amend the message and force commit:: - - $ git commit --amend - $ git push -f origin my_branch - -If you're asked to make changes on your code you can stage them and amend the commit:: - - $ git add my_changed_files - $ git commit --amend - $ git push -f origin my_branch - -If you need more Git expertise, a good resource is the `Git book `_. - -Templates ---------- - -satnogs-network uses `Django's template engine `_ templates. - -Frontend development --------------------- - -To be able to manage the required javascript libraries, install the development dependencies with npm:: - - $ npm install - -Development tasks like the download of assets, code linting and tests are managed with gulp:: - - $ gulp - -Frontend dependencies are stored in packages.json, handled by yarn. To add a new dependency, e.g. satellite.js, call:: - - $ yarn add satellite.js - -Manually add the new required files to the list of "assets" in packages.json, then start the download with:: - - $ gulp assets - -The assets are stored in the repository, thus don't forget to create a commit after you add/update/remove dependencies. - -Simulating station heartbeats ------------------------------ - -Only stations which have been seen by the server in the last hour (by default, can be customized by `STATION_HEARTBEAT_TIME`) -are taken into consideration when scheduling observations. In order to simulate an heartbeat of the stations 7, 23 and 42, -the following command can be used - - $ sudo docker-compose run web python manage.py update_station_last_seen 7 23 42 - -Coding Style ------------- - -#. Four space indentation (no tabs), two whitespace on html documents. -#. Use single quotes for strings. Double quotes used only for html attributes. -#. Keep lines shorter than 100 characters when possible (especially at python code) - -Follow the `PEP8 `_ and `PEP257 `_ Style Guides. - -Most important things: - -#. Separate top-level function and class definitions with two blank lines. -#. Method definitions inside a class are separated by a single blank line. -#. Use whitespace between comma seperated values. -#. Use white space between assignments and expressions (except parameter values). -#. Don't use whitespace before or after parentheses, brackets or braces. -#. Classes should use CamelCase naming. -#. Functions should use lowercase naming. - - -What to work on ---------------- -You can check `opened issues `_. We regurarly open issues for tracking new features. You pick one and start coding. diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst new file mode 100644 index 0000000..5cf8b24 --- /dev/null +++ b/docs/developer-guide.rst @@ -0,0 +1,77 @@ +Developer Guide +=============== + +Thank you for your interest in developing SatNOGS! +There are always bugs to file; bugs to fix in code; improvements to be made to the documentation; and more. + +The below instructions are for software developers who want to work on `satnogs-network code `_. + +Workflow +-------- + +When you want to start developing for SatNOGS, you should :doc:`follow the installation instructions `, then... + +#. Read CONTRIBUTING.md file carefully. + +#. Fork the `upstream repository `_ in GitLab. + +#. Code! + +#. Test the changes and fix any errors by running `tox `_. + +#. Commit changes to the code! + +#. When you're done, push your changes to your fork. + +#. Issue a merge request on Gitlab. + +#. Wait to hear from one of the core developers. + +If you're asked to change your commit message or code, you can amend or rebase and then force push. + +If you need more Git expertise, a good resource is the `Git book `_. + +Templates +--------- + +satnogs-network uses `Django's template engine `_ templates. + + +Frontend development +-------------------- + +To be able to manage the required javascript libraries, install the development dependencies with npm:: + + $ npm install + +Development tasks like the download of assets, code linting and tests are managed with gulp:: + + $ gulp + +Frontend dependencies are stored in packages.json, handled by yarn. To add a new dependency, e.g. satellite.js, call:: + + $ yarn add satellite.js + +Manually add the new required files to the list of "assets" in packages.json, then start the download with:: + + $ gulp assets + +The assets are stored in the repository, thus don't forget to create a commit after you add/update/remove dependencies. + +Simulating station heartbeats +----------------------------- + +Only stations which have been seen by the server in the last hour (by default, can be customized by `STATION_HEARTBEAT_TIME`) are taken into consideration when scheduling observations. +In order to simulate an heartbeat of the stations 7, 23 and 42, the following command can be used:: + + $ sudo docker-compose run web python manage.py update_station_last_seen 7 23 42 + +Coding Style +------------ + +Follow the `PEP8 `_ and `PEP257 `_ Style Guides. + +What to work on +--------------- +You can check `open issues `_. +We regurarly open issues for tracking new features. You pick one and start coding. diff --git a/docs/index.rst b/docs/index.rst index c5a2224..c03ff4e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,5 +6,5 @@ satnogs-network :maxdepth: 1 installation - contribute + developer-guide maintenance