Add Instructions For Pulling Main Into a Development Branch to Contributors Guide

[seanlaw]

Each time I fork the main repo and make a branch, I forget how to pull in changes from main into my local development branch. It would be good to document the basic steps in the Contributors guide:

1. Open a terminal
2. Change the current working directory to your local development repository (e.g., cd Git/stumpy_dev.git)
3. Check out your local development branch (e.g., git switch some_new_feature)
4. Commit all changes in your local development branch (e.g., git add some_file.py and git commit)
5. Fetch the branches and their respective commits from the upstream repository (e.g., git fetch upstream)
6. Check out your fork's local default branch (e.g., git checkout main)
7. Merge the changes from the upstream default branch - in this case, upstream/main - into your local default branch (e.g., git merge upstream/main). This brings your fork's default branch into sync with the upstream repository, without losing your local changes.
8. If your local main branch didn't have any unique commits, Git will perform a fast-forward. Otherwise, if your local main branch had unique commits, you may need to resolve conflicts. Note that this does not affect your development branch!
9. Next, switch over to your development branch (e.g., git switch some_new_feature)
10. Finally, merge the main branch into your development branch (e.g., git merge main)

You may see something like the following:

> git merge main
Auto-merging stumpy/aamp_stimp.py
Auto-merging stumpy/core.py
Auto-merging stumpy/mpdist.py
CONFLICT (content): Merge conflict in stumpy/mpdist.py
Auto-merging stumpy/mstumped.py
CONFLICT (content): Merge conflict in stumpy/mstumped.py
Auto-merging stumpy/ostinato.py
Auto-merging stumpy/stimp.py
CONFLICT (content): Merge conflict in stumpy/stimp.py
Auto-merging stumpy/stumped.py
CONFLICT (content): Merge conflict in stumpy/stumped.py
Automatic merge failed; fix conflicts and then commit the result.

You will need to open up the files tagged with CONFLICT and resolve the merge conflicts. Once that's done, you will need to commit the changes and push the commit (e.g., git push) back to Github.

[seanlaw]

@NimaSarajpoor Does this seem right to you? Did I miss anything?

[joehiggi1758]

@seanlaw @NimaSarajpoor since this seems solid for a beginner like me, I'd be happy to take this one!

[seanlaw]

@joehiggi1758 It's all yours! Note that there is already a Sync Your Fork with the Parent Repository in our Contributing Guide but it is pretty light. I think the extra details above should/could go there but perhaps as a "hidden cell" (i.e., that the user would need to click a button to expand in order to see the details) via Myst-NB (the addition of Myst-NB is relatively new for STUMPY and we use it to render all of our tutorials, including the Contributor guide so PLEASE do not hesitate to ask if you get moderately stuck!).

[seanlaw]

Some additional notes:

Since this is dealing with documentation (hosted on readthedocs.org) and not stumpy development code, you will need to look inside of the docs directory and install "documentation dependencies" by doing pip install -r requirements.txt (this is in docs/requirements.txt!!). After installing the dependencies, you can then "build" the docs locally by executing the setup.sh script (also in docs/setup.sh). A whole bunch of things will print to your screen as things are being built by sphinx (locally) and, at the end if you don't see any warnings/errors, you'll see something like:

The HTML pages are in _build/html.
Serving HTTP on :: port 8000 (http://[::]:8000/) ...

Do not "kill" this process as it is not running a local HTTP server that will allow you to view things from your browser and to check the rendered/built outputs. Then, fire up a browser tab and navigate to http://localhost:8000/_build/html/Contribute.html and you should be able to see your changes