Skip to content

Commit f7ce715

Browse files
author
Dave Cuthbert
authored
DOCSP-25767 add versioning documentation v1.0 (#96)
* DOCSP-25767 versioning information * DOCSP-25767 versioning information * DOCSP-25767 versioning information * DOCSP-25767 versioning information * DOCSP-25767 versioning information * DOCSP-25767 versioning information * Review Feedback * Review feedback * Review feedback * Review feedback * Review feeback * Staging fixes * Staging fixes * Force build * Force build
1 parent e14143c commit f7ce715

File tree

5 files changed

+191
-4
lines changed

5 files changed

+191
-4
lines changed

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,4 +30,5 @@ mdb-download-center = "`MongoDB Download Center <https://www.mongodb.com/try/dow
3030

3131
[substitutions]
3232
c2c-product-name = "Cluster-to-Cluster Sync"
33+
version = "{+version+}"
3334

‎source/index.txt

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,8 @@ Cluster-to-Cluster Sync
88
.. default-domain:: mongodb
99

1010
{+c2c-product-name+} provides continuous data synchronization or a
11-
one-time data migration between two MongoDB clusters in the same or
12-
hybrid environments. You can enable {+c2c-product-name+} with the
13-
:ref:`mongosync <c2c-mongosync>` utility.
11+
one-time data migration between two MongoDB clusters. You can enable
12+
{+c2c-product-name+} with the :ref:`mongosync <c2c-mongosync>` utility.
1413

1514
``mongosync`` can continuously synchronize data between two clusters.
1615
You can use ``mongosync`` to create dedicated analytics, development,
@@ -24,7 +23,8 @@ facilitate a one time data migration between clusters.
2423
To get started with ``mongosync``, refer to the :ref:`Quick Start Guide
2524
<c2c-quickstart>`. For more detailed information, refer to the
2625
:ref:`c2c-install` or :ref:`c2c-connecting` page that best fits your
27-
situation.
26+
situation. See also the :ref:`c2c-limitations` page for important
27+
restrictions.
2828

2929
.. include:: /includes/limitations-warning
3030

‎source/reference.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,4 +15,5 @@ Reference
1515
/reference/disaster-recovery
1616
/reference/limitations
1717
/reference/logging
18+
/reference/versioning
1819

‎source/reference/limitations.txt

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,10 @@ General Limitations
5454
- `Queryable Encryption
5555
<https://www.mongodb.com/docs/v6.0/core/queryable-encryption/>`__ is
5656
not supported.
57+
- After you replace the ``mongosync`` binary during an upgrade or a
58+
downgrade, you should drop all non-system databases in the destination
59+
cluster before starting the new binary. Syncing operations will
60+
restart from the beginning when you start the new processes.
5761

5862
MongoDB Community Edition
5963
-------------------------

‎source/reference/versioning.txt

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
.. _c2c-release-version-numbers:
2+
3+
========================
4+
``mongosync`` Versioning
5+
========================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
16+
{+c2c-product-name+} uses `Semantic Versioning 2.0.0
17+
<https://semver.org/>`__. Version numbers have the form ``X.Y.Z``, where
18+
``X`` is the major version, ``Y`` is the minor version, and ``Z`` is the
19+
patch version.
20+
21+
MongoDB uses the following guidelines to determine when to increment the
22+
version number for {+c2c-product-name+}:
23+
24+
- Major number: The release breaks backwards compatibility.
25+
- Minor number: The release includes significant new features that are
26+
backwards compatible.
27+
- Patch number: This release only includes small, backwards compatible
28+
changes.
29+
30+
31+
Currently Supported Versions
32+
----------------------------
33+
34+
If you are using an unsupported version of ``mongosync``, you may be
35+
asked to upgrade in order to receive support.
36+
37+
38+
MongoDB Server Version Compatibility and Support
39+
------------------------------------------------
40+
41+
{+c2c-product-name+} supports the following versions of MongoDB Server:
42+
43+
44+
.. list-table::
45+
:header-rows: 1
46+
:stub-columns: 1
47+
48+
* - ``mongosync`` Version
49+
- MongoDB Server Version
50+
51+
* - 1.0.0
52+
- 6.0.x
53+
54+
Considerations
55+
--------------
56+
57+
{+c2c-product-name+} has the following version related considerations:
58+
59+
Same Server Version
60+
~~~~~~~~~~~~~~~~~~~
61+
62+
{+c2c-product-name+} only supports syncing between the same version of
63+
MongoDB Server. All three :ref:`server version numbers
64+
<release-version-numbers>`, including the patch number, must be the
65+
same on both servers.
66+
67+
Support Lifecycle
68+
~~~~~~~~~~~~~~~~~
69+
70+
- Major releases are supported for at least one year from the first
71+
release in that series.
72+
- If a version of {+c2c-product-name+} only works with an unsupported
73+
version of MongoDB Server, that version of {+c2c-product-name+} is
74+
also unsupported.
75+
76+
Patch Releases
77+
~~~~~~~~~~~~~~
78+
79+
Only the latest version in each major release series receives new patch
80+
releases. For example, when version {+c2c-product-name+} 2.1.0 is
81+
released, version 2.0 would no longer receive patch releases. At the
82+
same time, version 1.3 would continue to receive patches until version
83+
1.4 was released.
84+
85+
Upgrade and Downgrade
86+
~~~~~~~~~~~~~~~~~~~~~
87+
88+
To upgrade, or downgrade ``mongosync``:
89+
90+
- Stop all currently running ``mongosync`` processes.
91+
- Drop all non-system databases in the destination cluster.
92+
- :ref:`Install <c2c-install>` new ``mongosync`` binaries.
93+
- :ref:`Start <c2c-api-start>` the ``mongosync`` processes using the new
94+
binaries.
95+
96+
.. warning::
97+
98+
The new ``mongosync`` processes do not resume any work that may have
99+
been in progress. Syncing operations restart from the beginning when
100+
you start the new processes.
101+
102+
Persistent Metadata
103+
~~~~~~~~~~~~~~~~~~~
104+
105+
During normal operation, ``mongosync`` creates metadata that is
106+
persisted to disk in the destination database. This metadata is not
107+
versioned and may change at any time.
108+
109+
Log Messages
110+
~~~~~~~~~~~~
111+
112+
Log message formats are not versioned and may change at any time. This
113+
includes changes to the message text, as well as the presence, absence,
114+
or contents of other fields in the message.
115+
116+
User scripts and applications should not rely on logging output. Scripts
117+
and applications should use the :ref:`monitoring API <c2c-api-progress>`
118+
to determine the current state of ``mongosync``.
119+
120+
Examples
121+
--------
122+
123+
The following examples illustrate the kinds of changes that would result
124+
in each type of version number update.
125+
126+
Major Releases
127+
~~~~~~~~~~~~~~
128+
129+
- Changes that make the new and old versions of ``mongosync`` produce
130+
different results on the destination cluster for the same set of
131+
inputs. Except:
132+
133+
- Bug fixes for cases where the older version of ``mongosync`` fails
134+
to replicate data.
135+
- When the earlier behavior is explicitly documented as unsupported.
136+
137+
- Changes to documented CLI parameters or configuration keys such that
138+
``mongosync`` rejects formerly valid input. Except:
139+
140+
- Bug fixes such as parsing or type errors.
141+
- Even though CLI parameters or configuration keys may be deprecated,
142+
the meaning of documented CLI parameters or configuration keys will
143+
never change. If needed, new parameters or keys will replace the
144+
older, deprecated entities.
145+
146+
- Changes that break compatibility with a supported version of MongoDB
147+
Server.
148+
- Dropping a version of the REST API. ``mongosync`` may dropping all
149+
older endpoints in favor of a new version of the API. There will never
150+
be any other types of backwards incompatible changes in the REST API.
151+
- Removing support for a previously supported MongoDB Server feature if
152+
``mongosync`` still supports a version of MongoDB Server that supports
153+
the feature.
154+
- If ``mongosync`` already supports a major version of MongoDB Server,
155+
changes that require new access privileges in order to continue
156+
supporting that version of MongoDB Server.
157+
158+
Minor Releases
159+
~~~~~~~~~~~~~~
160+
161+
- Adding support for a previously incompatible MongoDB Server version.
162+
- Requiring new access privileges for a previously unsupported major
163+
release of MongoDB Server.
164+
- Adding support for previously unsupported collection types.
165+
- Adding support for previously unsupported index types.
166+
- Adding new endpoints, new fields, or new accepted inputs in the REST API.
167+
- Adding new documented CLI options.
168+
- Adding new configuration keys or accepted values.
169+
170+
Patch Releases
171+
~~~~~~~~~~~~~~
172+
173+
- Backwards compatible bug fixes.
174+
- Performance regression fixes.
175+
- Performance improvements.
176+
- Changes to help text strings.
177+
- Changes to log text strings.
178+
- Changes to informational text in API responses, but not changes to
179+
enum-style string fields like "state".
180+
- Typo fixes.
181+

0 commit comments

Comments
 (0)