From 8e7b3a43eb6a015d256d127728c6d6b3aca68df8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Paulo=20V=20Martins?= Date: Sun, 15 Mar 2020 15:55:21 +0000 Subject: [PATCH 1/2] Fix small issues with docs --- docs/database.rst | 12 ++++++------ docs/faq.rst | 6 +++--- docs/nonstandard.rst | 4 ++-- docs/nonstandard/guid.rst | 2 +- docs/nonstandard/version6.rst | 4 ++-- docs/rfc4122/version2.rst | 4 ++-- docs/upgrading/3-to-4.rst | 10 +++++----- 7 files changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/database.rst b/docs/database.rst index 2db1a38..236df83 100644 --- a/docs/database.rst +++ b/docs/database.rst @@ -14,7 +14,7 @@ There are several strategies to consider when working with UUIDs in a database. Among these are whether to store the string representation or bytes and whether the UUID column should be treated as a primary key. We'll discuss a few of these approaches here, but the final decision on how to use UUIDs in a database is up -to you, since your needs will be different from those of others. +to you since your needs will be different from those of others. .. note:: @@ -178,7 +178,7 @@ Using As a Primary Key In the previous examples, we didn't use the UUID as a primary key, but it's logical to use the ``notes.uuid`` field as a primary key. There's nothing wrong -with this approach, but there are a couple points to consider: +with this approach, but there are a couple of points to consider: * InnoDB stores data in the primary key order * All the secondary keys also contain the primary key (in InnoDB) @@ -189,7 +189,7 @@ second point, if you are using the string version of the UUID (i.e., space, but every secondary key that uses that primary key will also be must larger. -For this reason, if you choose to use UUIDs as primary keys, it might be worth +For this reason, if you choose to using UUIDs as primary keys, it might be worth the drawbacks to use UUID bytes (i.e., ``char(16)``) instead of the string representation (see :ref:`database.bytes`). @@ -208,11 +208,11 @@ Using As a Unique Key Instead of :ref:`using UUIDs as a primary key `, you may choose to use an ``AUTO_INCREMENT`` column with the ``int unsigned`` data type as a primary key, while using a ``char(36)`` for UUIDs and setting a ``UNIQUE KEY`` -on this column. This will aid in lookups, while helping keep your secondary keys +on this column. This will aid in lookups while helping keep your secondary keys small. .. code-block:: sql - :caption: Use auto-incrementing column as primary key, with UUID as unique key + :caption: Use an auto-incrementing column as primary key, with UUID as a unique key :name: database.id-auto-increment-uuid-unique-key CREATE TABLE `notes` ( @@ -237,7 +237,7 @@ will become slower and slower. .. note:: See Percona's "`Storing UUID Values in MySQL`_" post, for more details on - performance of UUIDs as primary keys. + the performance of UUIDs as primary keys. To minimize these problems, two solutions have been devised: diff --git a/docs/faq.rst b/docs/faq.rst index 5342398..3674b2e 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -19,7 +19,7 @@ following message: .. code-block:: text - Package rhumsaa/uuid is abandoned, you should avoid using it. Use + Package rhumsaa/uuid is abandoned; you should avoid using it. Use ramsey/uuid instead. Don't panic. Simply execute the following commands with Composer: @@ -41,7 +41,7 @@ Why does ramsey/uuid use ``final``? You might notice that many of the concrete classes returned in ramsey/uuid are marked as ``final``. There are specific reasons for this choice, and I will -offer a few solutions for those looking to extend or mock the classes, for +offer a few solutions for those looking to extend or mock the classes for testing purposes. But Why? @@ -113,7 +113,7 @@ At the same time, ramsey/uuid is able to guarantee that neither a `downstream`_ code. UUIDs have specific rules that make them practically unique. ramsey/uuid ensures -that other code cannot change this expectation, while allowing your code and +that other code cannot change this expectation while allowing your code and third-party libraries to change how UUIDs are generated and to return different types of UUIDs not specified by `RFC 4122`_. diff --git a/docs/nonstandard.rst b/docs/nonstandard.rst index 9bae3e2..b35002e 100644 --- a/docs/nonstandard.rst +++ b/docs/nonstandard.rst @@ -14,10 +14,10 @@ Nonstandard UUIDs Outside of `RFC 4122`_, other types of UUIDs are in-use, following rules of their own. Some of these are on their way to becoming accepted standards, while -others have historical reasons for remaining valid today. Still others are +others have historical reasons for remaining valid today. Still, others are completely random and do not follow any rules. -For these cases, ramsey/uuid provides special functionality to handle these +For these cases, ramsey/uuid provides a special functionality to handle these alternate, nonstandard forms. Version 6: Ordered-time diff --git a/docs/nonstandard/guid.rst b/docs/nonstandard/guid.rst index 3c9613f..4b491da 100644 --- a/docs/nonstandard/guid.rst +++ b/docs/nonstandard/guid.rst @@ -142,7 +142,7 @@ arranged like this: Networking protocols usually use big-endian ordering, while computer processor architectures often use little-endian ordering. - The terms originated in Jonathan Swift's *Guilliver's Travels*, where the + The terms originated in Jonathan Swift's *Gulliver's Travels*, where the Lilliputians argue over which end of a hard-boiled egg is the best end to crack. diff --git a/docs/nonstandard/version6.rst b/docs/nonstandard/version6.rst index cbaca9f..aca5443 100644 --- a/docs/nonstandard/version6.rst +++ b/docs/nonstandard/version6.rst @@ -17,10 +17,10 @@ Version 6 UUIDs solve `two problems that have long existed`_ with the use of :ref:`version 1 ` UUIDs: 1. Scattered database records -2. Inability to sort by identifier in a meaningful way (i.e., insert order) +2. Inability to sort by an identifier in a meaningful way (i.e., insert order) To overcome these issues, we need the ability to generate UUIDs that are -*monotonically increasing*, while still providing all the benefits of version +*monotonically increasing* while still providing all the benefits of version 1 UUIDs. Version 6 UUIDs do this by storing the time in standard byte order, instead of diff --git a/docs/rfc4122/version2.rst b/docs/rfc4122/version2.rst index 49e6612..44800c4 100644 --- a/docs/rfc4122/version2.rst +++ b/docs/rfc4122/version2.rst @@ -109,7 +109,7 @@ If using the *person* or *group* domains, ramsey/uuid will attempt to look up these values from the local machine. On `POSIX`_ systems, it will use ``id -u`` and ``id -g``, respectively. On Windows, it will use ``whoami`` and ``wmic``. -The *org* domain is site-defined. Its intent it to identify the organization +The *org* domain is site-defined. Its intent is to identify the organization that generated the UUID, but since this can have different meanings for different companies and projects, you get to define its value. @@ -201,7 +201,7 @@ Limited Uniqueness ------------------ With the inclusion of the local identifier and domain comes a serious limitation -in the amount of unique UUIDs that may be created. This is because: +in the number of unique UUIDs that may be created. This is because: 1. The local identifier replaces the lower 32 bits of the timestamp. 2. The domain replaces the lower 8 bits of the clock sequence. diff --git a/docs/upgrading/3-to-4.rst b/docs/upgrading/3-to-4.rst index dc6aa47..f89e4ed 100644 --- a/docs/upgrading/3-to-4.rst +++ b/docs/upgrading/3-to-4.rst @@ -36,7 +36,7 @@ There are a lot of new features in ramsey/uuid! Here are a few of them: * Rfc4122\\NilUuid * Add classes to represent version 6 UUIDs, GUIDs, and nonstandard - (non-RFC 4122 variant) UUIDs: + (non-RFC 4122 variants) UUIDs: * :php:class:`Nonstandard\\UuidV6 ` * :php:class:`Nonstandard\\Uuid ` @@ -70,7 +70,7 @@ standard functionality and API found in version 3 will not differ much. use :php:interface:`UuidInterface `. * The :ref:`return types for three methods ` defined on :php:interface:`UuidInterface ` have - changed, breaking backward compatibility. **Take note, and update your code.** + changed, breaking backwards compatibility. **Take note and update your code.** * :ref:`There are a number of deprecations. ` These shouldn't affect you now, but please take a look at the recommendations and update your code soon. These will go away in ramsey/uuid version 5. @@ -94,7 +94,7 @@ standard functionality and API found in version 3 will not differ much. composer require ramsey/uuid:"^3 || ^4" This will allow any `downstream users`_ of your project who aren't ready to - upgrade to version 4 the ability to continue using your project, while + upgrade to version 4 the ability to continue using your project while deciding on an appropriate upgrade schedule. If your downstream users do not specify ramsey/uuid as a dependency, and @@ -156,7 +156,7 @@ Changed Return Types #################### The following :php:interface:`UuidInterface ` -method return types have changed in version 4, and you will need to update your +method return types have changed in version 4 and you will need to update your code, if you use these methods. .. list-table:: Changed UuidInterface method return types @@ -370,7 +370,7 @@ Builder\\UuidBuilderInterface * - Method - Description * - ``build()`` - - Second parameter used to accept ``array $fields``; now accepts ``string $bytes`` + - The second parameter used to accept ``array $fields``; now accepts ``string $bytes`` Converter\\TimeConverterInterface --------------------------------- From 62fdcbbed025f1e7994fe688754ed5dc92d469e5 Mon Sep 17 00:00:00 2001 From: Joao Paulo V Martins Date: Sun, 15 Mar 2020 16:43:57 +0000 Subject: [PATCH 2/2] Update docs/database.rst Co-Authored-By: Ben Ramsey --- docs/database.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/database.rst b/docs/database.rst index 236df83..8b859f3 100644 --- a/docs/database.rst +++ b/docs/database.rst @@ -189,7 +189,7 @@ second point, if you are using the string version of the UUID (i.e., space, but every secondary key that uses that primary key will also be must larger. -For this reason, if you choose to using UUIDs as primary keys, it might be worth +For this reason, if you choose to use UUIDs as primary keys, it might be worth the drawbacks to use UUID bytes (i.e., ``char(16)``) instead of the string representation (see :ref:`database.bytes`).