Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates to developer documentation #165

Closed
wants to merge 1 commit into from
Closed

Updates to developer documentation #165

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 63 additions & 4 deletions docs/source/for_developers/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,64 @@
************
Contributing
************
*************************
How to Contribute to Dysh
*************************

Want to contribute to `dysh`?
tl;dr: Create an issue if you find a bug. Create a pull request if you want to contribute code

Setting up a Dysh Development Environment
=========================================

In order to contribute to Dysh, you will need the following:

In order to set up a Dysh development environment, you will need the following:
#. `git <https://git-scm.com/>`_
#. `Python 3.9 <https://www.python.org/downloads/>`_
#. `Hatch <https://hatch.pypa.io/latest/install/>`_
#. `Pre-commit <https://pre-commit.com/#install>`_


See {TODO} for help on setting up these pre-requisites on your development platform
Then, you can:

.. code-block:: bash

git clone https://github.com/GreenBankObservatory/dysh.git
cd dysh
pre-commit install # Install the pre-commit hooks into your git repo
hatch shell # Create virtual env, install dependencies, and activate the environment


Contributing Code
=================

All code contributions will require:
#. `A GitHub account <https://github.com/signup>`_
#. `A fork the Dysh repo <https://github.com/GreenBankObservatory/dysh/fork>`_
#. An issue to be created


Two example workflows:

Feature Request/Bug Report
++++++++++++++++++++++++++

1. Check the `Dysh Issues <https://github.com/GreenBankObservatory/dysh/issues?q=>`_ to see if the bug/feature has already been reported/requested
2. If not, `create an Issue <https://github.com/GreenBankObservatory/dysh/issues/new>`_
3. Dysh developers will communicate with you via the Issue to help diagnose the bug

Bugs will be fixed as developer time allows.

I want to add a feature/fix a bug
+++++++++++++++++++++++++++++++++

I want to fix a bug
If you think you know how to fix the bug, we would welcome a bug fix!

1. In (a clone of) your fork, create a "feature branch" with a descriptive name like ``desc-of-your-bug``
2. Commit code to fix the bug
3. Create a `pull request <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_
4. Wait for Dysh developers to communicate with you further!


6. Check the `Dysh Issues <https://github.com/GreenBankObservatory/dysh/issues?q=>`_ to see if a similar feature has already been requested
7. If not, `create an Issue <https://github.com/GreenBankObservatory/dysh/issues/new>`_ describing the feature
8. Dysh developers will communicate with you via the Issue to help diagnose the bug
50 changes: 31 additions & 19 deletions docs/source/for_developers/doc_standards.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,45 +2,57 @@
Documentation
*************

Setting Up Sphinx Autobuilds
============================
How does it work, and how can you contribute to it?

Here are the steps to set up Sphinx autobuilds so that you can check your documentation edits live.
How to Contribute to Dysh Docs
==============================

1. First, navigate to your `dysh` root directory and activate the `hatch` environment.
Local Builds
++++++++++++

.. code-block:: bash
The first thing you'll want to do is get the docs building locally. This makes it very easy to develop, and you can be *nearly certain* that the docs will build on Read the Docs if they have successfully built locally (assuming you've rememembered to commit all your files...)

$ hatch shell
To run a live docs server (i.e. reload on changes)

2. Next, tell hatch to run the docs. The docs will be published at `http://127.0.0.1:8000/`.
.. code-block:: sh

.. code-block:: bash
cd "$DYSH_REPO_ROOT"
hatch run docs

(dysh) $ hatch run docs
You can pass any arguments through to ``sphinx-autobuild``, e.g. to bind to a specific host and port:

3. If you would like the docs to publish at a specific host and port, such as `http://thales:9876`, then add the appropriate flags:
.. code-block:: sh

.. code-block:: bash

(dysh) $ hatch run docs --host thales --port 9876

4. You may now make changes in the `dysh/docs/` directory and see the live changes at the appropriate URL in your browser. To close the server, simply `CTRL+C`.
cd "$DYSH_REPO_ROOT"
hatch run docs --host 0.0.0.0 --port 8001

Docstring Format
================

All Python functions must contain a docstring which follows the NumPy convention. You can learn more about this convention here: https://numpydoc.readthedocs.io/en/latest/format.html

Mermaid Diagrams
================
Flowcharts/Diagrams
+++++++++++++++++++

Where possible, please prefer Mermaid to pre-rendered flowcharts/diagrams. It makes it easy to embed the full source in the docs, which makes future edits significantly easier.

Diagrams can be directly in these text files by using the `sphinxcontrib-mermaid` package. Here's an example:
Dysh supports Mermaid Diagrams via the ``sphinxcontrib-mermaid`` package. Here's an example:

.. mermaid::

flowchart LR
A[Item 1] --> B[Item 2]
B --> C[Item 3]

To learn more, see the `package documentation <https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/>`_. Mermaid also offers an `online editor <https://mermaid.live>`_ which can be used to design diagrams.
To learn more, see the `sphinxcontrib-mermaid documentation <https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/>`_. Mermaid also offers an `online editor <https://mermaid.live>`_ which can be used to design diagrams.

Read the Docs
=============

Dysh's documentation is hosted on Read the Docs, at https://readthedocs.org/projects/dysh/. Docs are built directly from the Dysh GitHub repo.

RTD hosts several different active versions of Dysh documentation:

- ``latest``: built from the latest commit on ``main``
- ``stable``: built from that latest stable version tag
- ``release-X.Y``/``vX.Y``: built from the latest commit on a given release branch
177 changes: 123 additions & 54 deletions docs/source/for_developers/git_workflows.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,84 +1,153 @@
*************
Git Workflows
*************
************
Git Workflow
************

Branches
========
Background
==========

The development team employs a GitFlow workflow with personal branching. This means that code in the `main` branch should always be in a releasable state. Developers should maintain their own development branches and commit changes to a `release-x.y.z` branch. When it's time to release, a dedicated team member will merge the `release-x.y.z` branch with the `main` branch and tag it accordingly.
Dysh uses the `OpenAstronomy model for its branching and release structure <https://packaging-guide.openastronomy.org/en/latest/releasing.html#releasing-from-branches>`_. In practice, this essentially means that we are using a standard "feature branch" workflow, where new features are added via Pull Requests based on ``main``.

If you are an external collaborator, you will need to create Pull Requests from a fork of Dysh, but the instructions below should otherwise be fairly similar.

Developers are welcome to manage their git workflow however they want, but using the `GitHub CLI <https://cli.github.com/>`_ or `GitHub Desktop <https://desktop.github.com/>`_ simplify many operations.

How to Contribute
=================


There are two types of workflow:
1. Contributing to a future release. This is the most common workflow
2. Patching a previous release. This involves changes to a "release branch" -- changes will *not* go on `main`

Below is a diagram demonstrating both of these workflows. They are explored in more depth farther down.

.. mermaid::

%%{init: { 'theme': 'base' } }%%
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true,'mainBranchOrder': 10}} }%%

gitGraph
commit id: "1"
commit id: "2"
branch release-x.y.z order: 1
commit id: "3"
branch personB-devel order: 3
branch personA-devel order: 2
commit id: "4"
checkout personB-devel
commit id: "5"
commit id: "6"
checkout personA-devel
commit id: "7"
commit id: "8"
checkout release-x.y.z
merge personA-devel id: "9"
commit id: "10"
checkout personB-devel
merge release-x.y.z id: "11"
commit id: "12"
commit id: "13"
checkout release-x.y.z
merge personB-devel id: "14"

commit id: "freeze 0.2" tag: "v0.3dev"
branch v0.2 order: 11

checkout v0.2
commit id: "start v0.2 beta test" tag: "v0.2.0b1"

branch v0.2.0b1_fix order: 14
commit id: "fix bugs from beta"
checkout v0.2
merge v0.2.0b1_fix id: "Release v0.2.0rc1" tag: "v0.2.0rc1"
commit id: "Release v0.2.0" tag: "v0.2.0"
commit id: "Bug fix for v0.2" tag: "v0.2.1"
checkout v0.2

checkout main
branch feature_x order:3
commit id: "start feature x"
commit id: "finish feature x"
checkout main
merge release-x.y.z id: "15" tag: "release-x.y.z"
merge feature_x id: "freeze 0.3" tag: "v0.4dev"

Releases
========
branch v0.3 order:100
commit id: "start v0.3 beta test" tag: "v0.3.0b1"
checkout main

Release branches will be locked once work on the next release begins.
branch feature_y order:1
checkout feature_y
commit id:"implement feature y"
checkout main

Setting up your own development branch
======================================
Contribute to ``main`` (Add to a Future Release)
++++++++++++++++++++++++++++++++++++++++++++++++

In the directory you want to work in, set up the repo:

`$ git clone git@github.com:GreenBankObservatory/dysh.git`
Primary development is always done on a feature branch off of `main`. The only way for code to get into `main` is via a `Pull Request <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_ on the `Dysh GitHub <https://github.com/GreenBankObservatory/dysh>`_. A Pull Request is essentially a group of commits with a common purpose, and it is associated with a discussion thread. It encapsulates both the code changes themselves, and the explanation of why they are being made, how they work, etc.

`$ cd dysh`
Here is the lifecycle of a simple Pull Request:

`$ git checkout [branch-name]`
.. code-block:: sh

with the [branch-name] replaced by the current release or other branch. Currently, this is "release-0.2.0". Then setup your own development branch with your first name followed by "-devel":
git checkout main
git fetch origin main
git checkout -b my-cool-new-feature
# <make some code changes>
git commit -am "Desc of changes"
# <make some code changes>
git commit -am "More changes"
git push origin my-cool-new-feature

`$ git checkout [name-devel]`
At this point, the developer considers the work complete, and the Dysh GitHub has a new branch, ``my-cool-new-feature``, and the developer's repo will look like:

Now make and activate a python virtual environment so your work doesn't impede or break other concurrent projects. Whenever you do some work, make sure you are in your own development branch. When you are ready to merge changes made by other developers into your own branch,
.. mermaid::

`$ git checkout release-0.2.0`
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true}} }%%

`$ git pull`
gitGraph
commit id:" "
branch my-cool-new-feature
checkout my-cool-new-feature
commit id: "Desc of changes"
commit id: "More changes"

`$ git checkout [name-devel]`
Now they can open a Pull Request in the Dysh repo on GitHub.

`$ git merge release-0.2.0`
At this point, a few things happen:

When you are ready to commit changes, review what's been changed with
1. GitHub CI kicks off, which runs code quality checks and unit tests
2. Another developer will review your code contribution
3. Discussion of the new feature will occur
4. Eventually, the PR will be accepted or rejected
- If it is accepted, it will be merged into ``main`` and be a part of the next release
- If it is rejected, it will go nowhere

`$ git status`

and then add the intended files using
If accepted, the Dysh repo will now look like:

`$ git add [path/to/changed/file]`
.. mermaid::

check `dysh/.gitignore` to make sure you are not adding ignored files (virtual environment data, `_build/`, etc.). Then commit and push with
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true}} }%%

`$ git commit -m "[this is my commit message]"`
gitGraph
commit id:" "
branch my-cool-new-feature
checkout my-cool-new-feature
commit id: "Desc of changes"
commit id: "More changes"
checkout main
merge my-cool-new-feature

`$ git push`

The first time you run this, it will give a command about setting the origin upstream. Simply copy and run that command. Users of GitHub Desktop can also achieve all of these above steps using the app interface. Next, go to the `dysh GitHub page <https://github.com/GreenBankObservatory/dysh/>`_ and submit a pull request.


Contribute to a Previous Release (Add to a release branch)
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

In this example, release ``v0.2.0`` has been released, and development has started on ``v0.3.0`` (on ``main``). Then, a bug is reported in ``v0.2.0``, necessitating a bug fix.


.. mermaid::

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true}} }%%

gitGraph

commit id: "freeze 0.2" tag: "v0.3dev"
branch v0.2

checkout v0.2

checkout main
commit id: " "
checkout v0.2

commit id: "Release 0.2.0" tag: "v0.2.0"
branch v0.2.0-bug-fix
commit id: "fix bug"
checkout v0.2
merge v0.2.0-bug-fix id: "Release v0.2.1"
commit id: "Release 0.2.1" tag: "v0.2.1"

checkout v0.2

checkout main
commit id: " "
9 changes: 5 additions & 4 deletions docs/source/for_developers/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,16 @@
For Developers
**************

Here's some info that developers might find useful
Documentation specifically for people who want to contribute code to Dysh

.. toctree::
:maxdepth: 2

setup_dev_env
contributing
install
git_workflows
doc_standards

install
github_integrations
git_workflows
black
terminal_messages
Loading