.. _contributing: ********************** Contributing to stglib ********************** .. contents:: Table of contents: :local: .. note:: We used `Contributing to xarray `_ as a guide, which in turn came from the `Pandas Contributing Guide `_. Overview ======== We welcome your skills and enthusiasm! There are numerous opportunities to contribute beyond just writing code. All contributions, including bug reports, bug fixes, documentation improvements, enhancement suggestions, and other ideas are welcome. Where to start? =============== We need your help. All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome. If you are brand new to open-source development, we recommend going through `stglib's GitLab "issues" tab `_ to find issues that interest you, discuss issues, to report new issues or propose new features. .. _contributing.bug_reports: Bug reports and enhancement requests ==================================== Bug reports are an important part of making *stglib* more stable. Having a complete bug report will allow others to reproduce the bug and provide insight into fixing. To indicate desire to work on an issue, post your intent and ideas in the issues tab. Follow the guidance here to set up your environment in python. We do not yet have a public mailing list. USGS folks can ask questions and follow discussions in the GS-CMHRP-CCH-TimeSeriesData team, however we encourage all to publicly post and discuss issues on GitLab in `stglib's GitLab "issues" tab `_, so that we can advance this package as a user community. Bug reports are an important part of improving our package. Having a complete bug report will allow others to reproduce the bug and provide insight into fixing. See `this stackoverflow article `_ for tips on writing a good bug report. Trying the bug-producing code out on the *master* branch is often a worthwhile exercise to confirm the bug still exists. It is also worth searching existing bug reports and pull requests to see if the issue has already been reported and/or fixed. Bug reports must: #. Include a short, self-contained Python snippet reproducing the problem. You can format the code nicely by using `GitHub Flavored Markdown `_ #. Explain why the current behavior is wrong/not desired and what you expect instead. The issue will then show up to the *stglib* community and be open to comments/ideas from others. .. _contributing.github: Working with the code ===================== Now that you have an issue you want to fix, enhancement to add, or documentation to improve, you need to learn how to work with GitLab and the *stglib* code base. .. _contributing.version_control: Version control, Git, and GitLab -------------------------------- To contribute, you will need to know git. To the new user, working with Git is one of the more daunting aspects of contributing to *stglib*. It can very quickly become overwhelming, but sticking to the guidelines below will help keep the process straightforward and mostly trouble free. As always, if you are having difficulties please feel free to ask for help. The code is hosted on `GitLab `_. To contribute you will need to sign up for an account on USGS GitLab. We use `Git `_ for version control to allow many people to work together on the project. Some great resources for learning Git: * the `GitHub help pages `_. * the `NumPy's documentation `_. "Every single developer working on the project has their code reviewed, and we\'ve come to see it as friendly conversation from which we all learn and the overall code quality benefits. Therefore, please don’t let the review discourage you from contributing: its only aim is to improve the quality of project, not to criticize (we are, after all, very grateful for the time you’re donating!)." * Matthew Brett's `Curious Coder\'s Guide To Git `_. .. _contributing.forking: Forking ------- You will need your own fork to work on the code. Go to the `stglib project page `_ and hit the ``Fork`` button. You will want to clone your fork to your machine:: git clone https://code.usgs.gov/your-user-name/stglib.git cd stglib git remote add upstream https://code.usgs.gov/cmgp/stglib.git This creates the directory `stglib` and connects your repository to the upstream (main project) *stglib* repository. .. _contributing.dev_env: Creating a development environment ---------------------------------- To test out code changes, you'll need to build *stglib* from source, which requires a Python environment. If you're making documentation changes, you can skip to `contributing.documentation` but you won't be able to build the documentation locally before pushing your changes. .. _contributing.dev_python: Creating a Python Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Before starting any development, you'll need to create an isolated stglib development environment: - We recommend installing the IOOS conda environment per these instructions\: `Installing the IOOS Environment `_ - Make sure your conda is up to date with the command (``conda update conda``) - Make sure that you have cloned the repository - ``cd`` to the *stglib* source directory (your fork, locally, on your own machine) - install *stglib* per `Installation ` At this point you should be able to import *stglib* from your locally built version in a python interpreter or in jupyter-notebook:: $ python # start an interpreter >>> import stglib >>> stglib.__version__ '0.1.0+12.gd81f135' The above procedure created a new environment, and did not touch any of your existing environments, nor any existing Python installation. To view your environments:: conda info -e To return to your root (or base) environment:: conda deactivate See the full conda docs `here `__. Creating a git branch --------------------- You want your master branch to reflect only production-ready code, so create a feature branch for making your changes. For example:: git branch shiny-new-feature git checkout shiny-new-feature The above can be simplified to:: git checkout -b shiny-new-feature This changes your working directory to the shiny-new-feature branch. Keep any changes in this branch specific to one bug or feature so it is clear what the branch brings to *stglib*. You can have many "shiny-new-features" as individual branches and switch in between those branches using the ``git checkout the-feature-branch`` command. To update your shiny-new-feature branch, you need to retrieve the changes from the master branch:: git fetch upstream git rebase upstream/master Keep in mind, `upstream` refers to the original version of *stglib* at ``, not to be confused with the term `origin`, which is your fork of *stglib* at ``. The fetch and rebase commands will replay your commits (changes) on top of the latest *stglib* git master. If this leads to merge conflicts, you must resolve these before submitting your pull request. If you have uncommitted changes that you are not ready to commit yet, you will need to ``git stash`` them prior to updating. ``git stash`` will effectively store your changes and they can be reapplied with ``git stash pop`` after updating. .. _contributing.documentation: Contributing to the documentation ================================= If you're not the developer type, contributing to the documentation is still of huge value. You don't even have to be an expert on *stglib* to do so! In fact, there are sections of the docs that are worse off after being written by experts. If something in the docs doesn't make sense to you, updating the relevant section after you figure it out is a great way to ensure it will help the next person. .. contents:: Documentation: :local: About the *stglib* documentation -------------------------------- The documentation is written in `reStructuredText `__, which is almost like writing in plain English, and built using `Sphinx `__. The Sphinx Documentation has an excellent `introduction to reST `__. Review the Sphinx docs to perform more complex changes to the documentation as well. Some other important things to know about the docs: - The *stglib* documentation consists of two parts: the docstrings in the code itself and the docs in this folder ``stglib/doc/``. The docstrings are meant to provide a clear explanation of the usage of the individual functions, while the documentation in this folder consists of tutorial-like overviews per topic together with some other information (what's new, installation, etc). - The docstrings follow the **Numpy Docstring Standard**, which is used widely in the Scientific Python community. This standard specifies the format of the different sections of the docstring. See `this document `_ for a detailed explanation, or look at some of the existing functions to extend it in a similar manner. - `stglib` documentation is organized by instrument type - There is an index for all the documentation called ``index.rst`` and if you make a new documentation file for some new instrument, be sure to include it in a ``toctree`` in ``index.rst`` How to build the *stglib* documentation --------------------------------------- Requirements ~~~~~~~~~~~~ Follow the instructions on creating a development environment above, and to build the docs you need to create a new environment with the environment file ``doc/environment.yml``. .. code-block:: # Create and activate the docs environment conda env create -f doc/environment.yml conda activate stglib-docs # Build and install stglib pip install -e . Building the documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~ Navigate to your local ``stglib/doc/`` directory in the console and run:: make html Then you can find the HTML output in the folder ``stglib/doc/build/html/``. The first time you build the docs, it will take longer because it has to run all the code examples and build all the generated docstring pages. In subsequent evocations, sphinx will try to only build the pages that have been modified. If you want to do a full clean build, do:: make clean make html .. _contributing.code: Contributing to the code base ============================= .. contents:: Code Base: :local: Code standards -------------- Writing good code is not just about what you write. It is also about *how* you write it. We expect any new code to be well documented, both in the code itself and for there to be explanations and tutorials similar to what already exists in the ``doc/`` directory. We expect new code to follow the structure of the existing code. In addition, because a lot of people use our library, it is important that we do not make sudden changes to the code that could have the potential to break a lot of user code as a result, that is, we need it to be as *backwards compatible* as possible to avoid mass breakages. Code Formatting ~~~~~~~~~~~~~~~ You must set up `pre-commit hooks `_ to automatically format the code every time you make a git commit. This can be done by running:: pre-commit install from the root of the stglib repository. You can skip the pre-commit checks with ``git commit --no-verify``. Integrated development environments also help with code formatting: - `spyder `_ installed by ``conda install spyder`` - `VS Code `_ - `Atom `_ - `pycharm free community edition `_ Backwards Compatibility ~~~~~~~~~~~~~~~~~~~~~~~ Please try to maintain backward compatibility. If you think breakage is required, clearly state why as part of the pull request. Also, be careful when changing method signatures and add deprecation warnings where needed. .. _contributing.ci: Testing With Continuous Integration ----------------------------------- We use continuous integration testing, which evaluates the code each time code is ``pushed`` to GitLab. The *stglib* test suite consists of the files in ``stglib/tests/``, and are run automatically by `GitLab Pipelines `__, a continuous integration service, once your pull request is submitted. You may wish to run tests on your local branch before pushing to GitLab or submitting the pull request. There are several types of testing: Please use `pytest `_ for new tests. A pull-request will be considered for merging when you have an all 'green' build. If any tests are failing, then you will get a red 'X', where you can click through to see the individual failed tests. .. _contributing.tdd: Test-driven development/code writing ------------------------------------ All tests should go into the ``tests`` subdirectory of the specific package. This folder contains many current examples of tests, and we suggest looking to these for inspiration. `test-driven development (TDD) `_: This development process "relies on the repetition of a very short development cycle: first the developer writes an (initially failing) automated test case that defines a desired improvement or new function, then produces the minimum amount of code to pass that test." So, before actually writing any code, you should write your tests. Often the test can be taken from the original GitLab issue. However, it is always worth considering additional use cases and writing corresponding tests. *stglib* maintainers will ask that your code include tests when receiving a pull request. Therefore, it is worth getting in the habit of writing tests ahead of time so this is never an issue. For more information about how to write tests, the xarray maintainers have `writing tests for xarray `_ We will include more information here as stglib grows. Contributing your changes to *stglib* (how to use git) ====================================================== Committing your code -------------------- Keeping style fixes to a separate commit will make your pull request more readable. Once you've made changes, you can see them by typing:: git status If you have created a new file, it is not being tracked by git. Add it by typing:: git add path/to/file-to-be-added.py Doing 'git status' again should give something like:: # On branch shiny-new-feature # # modified: /relative/path/to/file-you-added.py # The following defines how a commit message should be structured: * A subject line with `< 72` chars. * One blank line. * Optionally, a commit message body. Please reference the relevant GitLab issues in your commit message using ``#1234``. Now you can commit your changes in your local repository:: git commit -m Pushing your changes -------------------- When you want your changes to appear publicly on your GitLab page, push your forked feature branch's commits:: git push origin shiny-new-feature Here ``origin`` is the default name given to your remote repository on GitLab (your fork of stglib). You can see the remote repositories:: git remote -v If you added the upstream repository as described above you will see something like:: origin https://code.usgs.gov/yourname/stglib.git (fetch) origin https://code.usgs.gov/yourname/stglib.git (push) upstream https://code.usgs.gov/cmgp/stglib.git (fetch) upstream https://code.usgs.gov/cmgp/stglib.git (push) Now your code is on GitLab, but it is not yet a part of the *stglib* project. For that to happen, a pull request needs to be submitted on GitLab. Review your code ---------------- When you're ready to ask for a code review, file a pull request. Before you do, once again make sure that you have followed all the guidelines outlined in this document regarding code style, tests, performance tests, and documentation. You should also double check your branch changes against the branch it was based on: #. Navigate to your repository on GitLab -- https://code.usgs.gov/yourname/stglib #. Click on ``Branches`` #. Click on the ``Compare`` button for your feature branch #. Select the ``base`` and ``compare`` branches, if necessary. This will be ``master`` and ``shiny-new-feature``, respectively. Finally, make the pull request ------------------------------ If everything looks good, you are ready to make a pull request. A pull request is how code from a local repository becomes available to the GitLab community and can be looked at and eventually merged into the master version. This pull request and its associated changes will eventually be committed to the master branch and available in the next release. To submit a pull request: #. Navigate to your repository on GitLab #. Click on the ``Merge Request`` button #. You can then click on ``Commits`` and ``Files Changed`` to make sure everything looks okay one last time #. Write a description of your changes in the ``Preview Discussion`` tab #. Click ``Send Pull Request``. This request then goes to the repository maintainers, and they will review the code. If you need to make more changes, you can make them in your branch, add them to a new commit, push them to GitLab, and the pull request will be automatically updated. Pushing them to GitLab again is done by:: git push origin shiny-new-feature This will automatically update your pull request with the latest code and restart the Travis Continuous Integration tests. Delete your merged branch (optional) ------------------------------------ Once your feature branch is accepted into upstream, you'll probably want to get rid of the branch. First, merge upstream master into your branch so git knows it is safe to delete your branch:: git fetch upstream git checkout master git merge upstream/master Then you can do:: git branch -d shiny-new-feature Make sure you use a lower-case ``-d``, or else git won't warn you if your feature branch has not actually been merged. The branch will still exist on GitLab, so to delete it there do:: git push origin --delete shiny-new-feature MR checklist ------------ - **Properly comment and document your code.** - **Test that the documentation builds correctly** by typing ``make html`` in the ``doc`` directory. This is not strictly necessary, but this may be easier than waiting for CI to catch a mistake. - **Test your code**. - Write new tests if needed. - Test the code. - **Properly format your code** - **Push your code and** `create a MR on GitLab `_. - **Use a helpful title for your merge request** by summarizing the main contributions rather than using the latest commit message. If this addresses an `issue `_, please `reference it `_.