search

nightscout / trio-docs

GNU Affero General Public License v3.0
10 stars 14 forks source link

Adds 'Frequently Asked Questions' page #81

Closed Natolida closed 1 week ago

Natolida commented 1 month ago
Natolida commented 1 month ago

Hey Team,

I think the FAQs page is at a good enough point to add to the docs, and we can continue to build from there. Would you mind reviewing the validity of the information? This is my first significant contribution, and I would hate for any information to be inaccurate.

Cheers, David

Natolida commented 1 month ago

Thanks @ebouchut, I appreciate your feedback! All suggested changes have been applied.

Natolida commented 1 month ago

Hey @tmhastings, I am wondering if it would be a good idea to get this in prior to the docs migration?

Natolida commented 1 month ago

Thanks team, all updated and should be ready to go.

Natolida commented 3 weeks ago

Was there anything else I needed to do for a merge?

ebouchut commented 3 weeks ago

@Natolida Our main branch, upstream/dev, has seen a lot of changes recently because we switched to Mkdocs as our website generation engine.
This is why, we first need to integrate them into your topic/feature/PR branch which is ... dev. Then we need to update the Table of Contents (TOC) which has moved to mkdocs.yml from docs/index.html. Finally, we also need to fix links that are now broken due to a change in the folder structure.

The PR branch is not supposed to be `dev', but don't worry, I'll explain how to fix that.

Merge Changes from Upstream

Integrate the recent changes from the upstream/dev branch into your dev branch.

cd trio-docs
source venv/bin/activate 

# Fetch the recent changes from the `upstream` repository (`nightscout/trio-docs`)
# - `origin` your remote clone repository (i.e. `Natolida/trio-docs`)
# and store them locally in the remote cache
git fetch upstream

# Fetch the recent changes from the `origin` repository (your remote clone repository: `Natolida/trio-docs`)
# and store them locally in the remote cache
# -p means prune, that is if remove branches from the remote `origin` cache that have been removed from `Natolida/trio-docs`
git fetch -p origin 

# Jump on your topic/feature/PR branch which is ... `dev`
git switch dev

# Rebase `dev` onto `upstream/dev`, that is replay the commits from `dev` on top of the `upstream/dev` branch.
# as if we tack your `dev` branch on top of `upstream/dev`
git rebase upstream/dev

# You will then get a conflict because Git noticed that
# the `docs/resources/FAQ.md` file exists in your branch 
# but not in the other.
# Git stopped rebasing to ask you to choose which one to keep.

# Display the current state of rebase and conflicts
git status

# Choose your version of the file 
git checkout --theirs -- docs/resources/FAQ.md

# I confirm: `--theirs` above denotes your file (on `dev`).
#
# When starting a `git rebase upstream/dev`:
# - Git jumps on `upstream/dev` which becomes `HEAD` (FYI `HEAD` is the tip of the current branch)
# - `--ours` always denotes `HEAD`(`upstream/dev` in this case)
# - `--theirs` denotes `dev` (your `dev` branch that is the one you were on when you ran `git rebase`)
#
# It is a bit far-fetched!
# It's just the opposite of what you expect.
# Linus probably expected someone to add software layers on top of its initial implementation of Git
# to make this more user-friendly and consistent.
#
# The rule of thumb is to find where `HEAD` points to.
# HEAD denotes `--ours` 
# During a `git rebase`:
# - `--ours`    ==> the branch you are rebasing (`upstream/dev`)
# - `--theirs` ==> the branch where you ran `git rebase` from (`dev`)

# To complicate things, it is the exact opposite for `git merge upstream/dev`
# See `git rebase` section here for a more visual explanation:
#   https://nitaym.github.io/ourstheirs/ 

# Inform Git that we resolved the conflict
git add docs/resources/FAQ.md

# Ask Git to continue Rebasing
git rebase --continue

# Git opens up an editor with the merge commit message.
# It is the same as your last commit.
# Left it as is, save and exit the editor

# Git continues rebasing the next commit
# There is another conflict. This time it is `docs/index.md`
git status # to have a look at which file is in conflict

# In this commit you added FAQS.md to the Table of Contents (TOC) which was in this file 
# This was back when the site used Sphinx as its website engine.
# Since then we have switched to Mkdocs and the TOC is now located in `mkdocs.yml` below the `nav:` section.
# We need to:
# - A) Remove the changes you made to `docs/index.md`
# - B) Add FAQS.md to the Table of Contents in `mkdocs.md`

# A) Ask git to forget about your changes to `docs/index.md` and use the ones from `upstream/dev`
git checkout --ours -- docs/index.md

# B) Add FAQS.md to the `nav:`section in `mkdocs.yml`
#    Edit `mkdocs.yml` 
#    Append this line to this section (at the bottom of the TOC)
#      - FAQ: ./resources/FAQ.md

YOUR_FAVORITE_EDITOR_HERE mkdocs.yml

# Inform Git that we have fixed the conflicts
git add mkdocs.yml docs/index.md

# Ask Git to continue rebasing
git rebase --continue

# Once asked, update the commit message like so:
#   Add FAQS to the Table of Contents
# Save and exit the editor.

# Congratulations, you are done rebasing!

# Remove the currently installed packages (i.e. dependencies) to start from a blank slate
python -m pip freeze --exclude-editable | xargs python -m pip uninstall -y

# Install the packages
pip install -r dev-requirements.txt
pip install -r requirements.txt

# You can now live-preview the changes you make to the TrioDocs locally
# See: https://github.com/nightscout/trio-docs?tab=readme-ov-file#preview-changes
mkdocs serve

# You now need to fix the links in the FAQ page as the directory structure has changed.
# The links on this page are now broken because `EN/latest/` has been dropped since the conversion to Mkdocs.
# You need to update them, commit a fix, and push the branch 

YOUR_FAVORITE_EDITOR_HERE docs/resources/FAQ.md
git commit -m "Fix broken links according to new folder structure"
git push origin

Fix dev Branch

IMPORTANT: Do the following once but ONLY AFTER PR #81 has been merged

The dev branch should not be used to hold the commits of your topic/feature. To fix this the soft way, we will wait for the PR to be merged first. Then we will move your dev branch so that it points to upstream/dev, like this:

cd trio-docs
source venv/bin/activate 

git fetch upstream
git fetch origin

git switch dev

# IMPORTANT: Make sure that you do not have files that are not committed (i.e. not under version control).
# If you have uncommitted files, here is how to stash your work in progress. 
# We will set these files aside on a plate with the tag "MyWIP", in a special drawer that Git calls the "stash". 
# We push this plate on top of the stack of plates already present in this drawer.
git stash push --include-untracked -m MyWIP

# In the future and on another branch, once you need to get these files 
# back into your working directory, ask git to retrieve the plate with the tag "MyWIP"
## git stash pop MyWIP

# Now we need to restore `dev` so that it points at the same commit as `upstream/dev`
# and make some cleaning in your working directory and staging area:
# - Restore a clean working directory
# - Empty the staging area
# - update the tip of the current branch (`dev`) so that it points to `upstream/dev`
git reset --hard upstream/dev

# Send this branch to your clone repository (`origin` => `Natolida/trio-docs`)
git push --force origin dev

How to create a Pull-Request

If you do not see the yellow box to create the PR:

GH Doc: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request#creating-the-pull-request

Natolida commented 1 week ago

Hey @ebouchut, I ran into some difficulties with your instructions above. To make things simple, I am going to close this PR. I will update my repo with the changes that have been made recently. I will then put my FAQ work back into its own branch and resubmit the PR.