From 9c617fffe2c5c5d0eb75680c19b4f916a2918977 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Im=C3=A8ne=20Goumiri?= Date: Mon, 17 Jun 2024 00:06:14 -0700 Subject: [PATCH] Rename `develop` branch to `main` in docs (#3) * Rename develop branch to main in docs ssapy doesn't have a develop branch on Github. All those references to `develop` are pretty confusing to a newcomer. * Revert accidental pybind11 update --- .codecov.yml | 2 +- README.rst | 8 +-- docs/source/contribution_guide.rst | 80 +++++++++++++++--------------- 3 files changed, 45 insertions(+), 45 deletions(-) diff --git a/.codecov.yml b/.codecov.yml index 8ecbe16..6754c37 100644 --- a/.codecov.yml +++ b/.codecov.yml @@ -19,7 +19,7 @@ github_checks: # Attempt to fix "Missing base commit" messages in the codecov UI. # Because we do not run full tests on package PRs, package PRs' merge -# commits on `develop` don't have coverage info. It appears that +# commits on `main` don't have coverage info. It appears that # codecov will give you an error if the pseudo-base's coverage data # doesn't all apply properly to the real PR base. # diff --git a/README.rst b/README.rst index 9b49376..ae5e20d 100644 --- a/README.rst +++ b/README.rst @@ -12,7 +12,7 @@ SSAPy - Space Situational Awareness for Python .. |docs_badge| image:: https://github.com/LLNL/SSAPy/actions/workflows/pages/pages-build-deployment/badge.svg :target: https://LLNL.github.io/SSAPy -.. |codecov_badge| image:: https://codecov.io/gh/LLNL/SSAPy/branch/develop/graph/badge.svg +.. |codecov_badge| image:: https://codecov.io/gh/LLNL/SSAPy/branch/main/graph/badge.svg :target: https://codecov.io/gh/LLNL/SSAPy SSAPy is a python package allowing for fast and precise orbital modeling. @@ -67,18 +67,18 @@ The API documentation may also be seen by doing: Contributing ------------ -Contributing to SSAPy is relatively easy. Just send us a `pull request `_. When you send your request, make `develop` the destination branch on the `SSAPy repository `_. +Contributing to SSAPy is relatively easy. Just send us a `pull request `_. When you send your request, make `main` the destination branch on the `SSAPy repository `_. Your PR must pass SSAPy's unit tests and documentation tests, and must be `PEP 8 `_ compliant. We enforce these guidelines with our CI process. To run these tests locally, and for helpful tips on git, see our `Contribution Guide `_. -SSAPy's `develop` branch has the latest contributions. Pull requests should target `develop`, and users who want the latest package versions, features, etc. can use `develop`. +SSAPy's `main` branch has the latest contributions. Pull requests should target `main`, and users who want the latest package versions, features, etc. can use `main`. Releases -------- For multi-user site deployments or other use cases that need very stable software installations, we recommend using SSAPy's `stable releases `_. -Each SSAPy release series also has a corresponding branch, e.g. `releases/v0.14` has `0.14.x` versions of SSAPy, and `releases/v0.13` has `0.13.x` versions. We backport important bug fixes to these branches but we do not advance the package versions or make other changes that would change the way SSAPy concretizes dependencies within a release branch. So, you can base your SSAPy deployment on a release branch and `git pull` to get fixes, without the package churn that comes with develop. +Each SSAPy release series also has a corresponding branch, e.g. `releases/v0.14` has `0.14.x` versions of SSAPy, and `releases/v0.13` has `0.13.x` versions. We backport important bug fixes to these branches but we do not advance the package versions or make other changes that would change the way SSAPy concretizes dependencies within a release branch. So, you can base your SSAPy deployment on a release branch and `git pull` to get fixes, without the package churn that comes with `main`. The latest release is always available with the `releases/latest` tag. diff --git a/docs/source/contribution_guide.rst b/docs/source/contribution_guide.rst index 982d7e4..e0ab339 100644 --- a/docs/source/contribution_guide.rst +++ b/docs/source/contribution_guide.rst @@ -30,17 +30,17 @@ and error prone. If possible, try to follow the **one-PR-one-feature** rule. Branches -------- -SSAPy's ``develop`` branch has the latest contributions. Nearly all pull -requests should start from ``develop`` and target ``develop``. +SSAPy's ``main`` branch has the latest contributions. Nearly all pull +requests should start from ``main`` and target ``main``. There is a branch for each major release series. Release branches -originate from ``develop`` and have tags for each point release in the +originate from ``main`` and have tags for each point release in the series. For example, ``releases/v0.14`` might have tags for ``0.14.0``, ``0.14.1``, ``0.14.2``, etc. versions of SSAPy. We backport important bug fixes to these branches, but we do not advance the package versions or make other changes that would change the way SSAPy concretizes dependencies. Currently, the maintainers manage these branches by -cherry-picking from ``develop``. See :ref:`releases` for more +cherry-picking from ``main``. See :ref:`releases` for more information. ---------------------- @@ -155,7 +155,7 @@ command: ``ssapy style`` has a couple advantages over running the tools by hand: #. It only tests files that you have modified since branching off of - ``develop``. + ``main``. #. It works regardless of what directory you are in. @@ -274,9 +274,9 @@ substantial changes to the core, we may request unit tests to increase coverage. You may notice that the Codecov tests fail even though you didn't modify any core files. This means that SSAPy's overall coverage - has increased since you branched off of develop. This is a good thing! + has increased since you branched off of ``main``. This is a good thing! If you really want to get the Codecov tests to pass, you can rebase off of - the latest develop, but again, this is not required. + the latest ``main``, but again, this is not required. ------------- @@ -284,7 +284,7 @@ Git Workflows ------------- SSAPy is still in the beta stages of development. Most of our users run off of -the develop branch, and fixes and new features are constantly being merged. So +the ``main`` branch, and fixes and new features are constantly being merged. So how do you keep up-to-date with upstream while maintaining your own local differences and contributing PRs to SSAPy? @@ -293,17 +293,17 @@ Branching ^^^^^^^^^ The easiest way to contribute a pull request is to make all of your changes on -new branches. Make sure your ``develop`` is up-to-date and create a new branch +new branches. Make sure your ``main`` is up-to-date and create a new branch off of it: .. code-block:: console - $ git checkout develop - $ git pull upstream develop + $ git checkout main + $ git pull upstream main $ git branch $ git checkout -Here we assume that the local ``develop`` branch tracks the upstream develop +Here we assume that the local ``main`` branch tracks the upstream ``main`` branch of SSAPy. This is not a requirement and you could also do the same with remote branches. But for some it is more convenient to have a local branch that tracks upstream. @@ -313,7 +313,7 @@ a message ``: descriptive message``. It is important to add descriptive message so that others, who might be looking at your changes later (in a year or maybe two), would understand the rationale behind them. -Now, you can make your changes while keeping the ``develop`` branch pure. +Now, you can make your changes while keeping the ``main`` branch pure. Edit a few files and commit them by running: .. code-block:: console @@ -328,7 +328,7 @@ Next, push it to your remote fork and create a PR: $ git push origin --set-upstream GitHub provides a `tutorial `_ -on how to file a pull request. When you send the request, make ``develop`` the +on how to file a pull request. When you send the request, make ``main`` the destination branch. If you need this change immediately and don't have time to wait for your PR to @@ -338,27 +338,27 @@ other branches: .. code-block:: console - $ git co develop - $ git branch - $ git checkout + $ git checkout main + $ git branch + $ git checkout $ git merge This can be done with each new PR you submit. Just make sure to keep this local -branch up-to-date with upstream ``develop`` too. +branch up-to-date with upstream ``main`` too. ^^^^^^^^^^^^^^ Cherry-Picking ^^^^^^^^^^^^^^ -What if you made some changes to your local modified develop branch and already +What if you made some changes to your local modified ``main`` branch and already committed them, but later decided to contribute them to SSAPy? You can use cherry-picking to create a new branch with only these commits. -First, check out your local modified develop branch: +First, check out your local modified ``main`` branch: .. code-block:: console - $ git checkout + $ git checkout Now, get the hashes of the commits you want from the output of: @@ -366,13 +366,13 @@ Now, get the hashes of the commits you want from the output of: $ git log -Next, create a new branch off of upstream ``develop`` and copy the commits +Next, create a new branch off of upstream ``main`` and copy the commits that you want in your PR: .. code-block:: console - $ git checkout develop - $ git pull upstream develop + $ git checkout main + $ git pull upstream main $ git branch $ git checkout $ git cherry-pick @@ -405,22 +405,22 @@ Other developers are constantly making contributions to SSAPy, possibly on the same files that your PR changed. If their PR is merged before yours, it can create a merge conflict. This means that your PR can no longer be automatically merged without a chance of breaking your changes. In this case, you will be -asked to rebase on top of the latest upstream ``develop``. +asked to rebase on top of the latest upstream ``main``. -First, make sure your develop branch is up-to-date: +First, make sure your ``main`` branch is up-to-date: .. code-block:: console - $ git checkout develop - $ git pull upstream develop + $ git checkout main + $ git pull upstream main Now, we need to switch to the branch you submitted for your PR and rebase it -on top of develop: +on top of ``main``: .. code-block:: console $ git checkout - $ git rebase develop + $ git rebase main Git will likely ask you to resolve conflicts. Edit the file that it says can't be merged automatically and resolve the conflict. Then, run: @@ -456,16 +456,16 @@ Now, look at the logs and save the hashes of any commits you would like to keep: $ git log -Next, go back to the original branch and reset it to ``develop``. -Before doing so, make sure that you local ``develop`` branch is up-to-date +Next, go back to the original branch and reset it to ``main``. +Before doing so, make sure that you local ``main`` branch is up-to-date with upstream: .. code-block:: console - $ git checkout develop - $ git pull upstream develop + $ git checkout main + $ git pull upstream main $ git checkout - $ git reset --hard develop + $ git reset --hard main Now you can cherry-pick relevant commits: @@ -490,20 +490,20 @@ If everything looks good, delete the backup branch: Re-writing History ^^^^^^^^^^^^^^^^^^ -Sometimes you may end up on a branch that has diverged so much from develop +Sometimes you may end up on a branch that has diverged so much from ``main`` that it cannot easily be rebased. If the current commits history is more of an experimental nature and only the net result is important, you may rewrite the history. -First, merge upstream ``develop`` and reset you branch to it. On the branch +First, merge upstream ``main`` and reset you branch to it. On the branch in question, run: .. code-block:: console - $ git merge develop - $ git reset develop + $ git merge main + $ git reset main -At this point your branch will point to the same commit as develop and +At this point your branch will point to the same commit as ``main`` and thereby the two are indistinguishable. However, all the files that were previously modified will stay as such. In other words, you do not lose the changes you made. Changes can be reviewed by looking at diffs: