Mercurial > evolve
changeset 655:dd5765ae91c3
doc: fix grammar, spelling, punctuation
I restrained myself to making only changes that turn bad English into
good English. There are still opportunities to improve, but other
changes require some discussion and review. This change should be
uncontroversial.
| author | Greg Ward <greg@gerg.ca> |
|---|---|
| date | Thu, 24 Jan 2013 18:05:59 -0500 |
| parents | c56109c9aebf |
| children | 4cd65437b704 |
| files | docs/evolve-collaboration.rst docs/evolve-faq.rst docs/evolve-good-practice.rst docs/from-mq.rst docs/index.rst docs/instability.rst docs/qsync.rst |
| diffstat | 7 files changed, 117 insertions(+), 118 deletions(-) [+] |
line wrap: on
line diff
--- a/docs/evolve-collaboration.rst Thu Jan 24 18:02:00 2013 -0500 +++ b/docs/evolve-collaboration.rst Thu Jan 24 18:05:59 2013 -0500 @@ -12,7 +12,7 @@ $ hg ci -m '[entities] remove magic' -Instant patch ! Note how the default phase of this changeset is (still) +Instant patch! Note how the default phase of this changeset is (still) in "draft" state. This is easily checkable:: @@ -30,7 +30,7 @@ "publishing" since they do not have the notion of non-public changesets (or mutable history). -During the transition from older mercurial servers to new ones, this will +During the transition from older Mercurial servers to new ones, this will happen often, so be careful. Now let's come back to our patch. Next hour sees good progress and Alice @@ -39,7 +39,7 @@ $ hg amend -m '[entities] fix frobulator (closes #42)' -Note that we also fix the commit message. (For recovering mq users: this +Note that we also fix the commit message. (For recovering MQ users: this is just like "hg qrefresh -m"). Before leaving, let's push to the central shared repository. That will @@ -65,7 +65,7 @@ brings her to yesterday's patch. Indeed the patch serial number has increased (827 still exists but has been obsoleted). -She understands that his original patch has been altered. But how did it +She understands that her original patch has been altered. But how did it evolve? The enhanced hgview shows the two patches. By default only the most @@ -84,7 +84,7 @@ Amend ... Stabilize -------------------- -Almost perfect ! Alice just needs to fix a half dozen grammar oddities in +Almost perfect! Alice just needs to fix a half dozen grammar oddities in the new docstrings and it will be publishable. Then, another round of: @@ -127,7 +127,7 @@ Except that rebase is a destructive (it removes information from the repository), unrecoverable operation, and the "evolve + obsolete" -combo, using changeset copy and obsolescence marker, provide evolution +combo, using changeset copy and obsolescence marker, provides evolution semantics by only adding new information to the repository (but more on that later).
--- a/docs/evolve-faq.rst Thu Jan 24 18:02:00 2013 -0500 +++ b/docs/evolve-faq.rst Thu Jan 24 18:05:59 2013 -0500 @@ -23,19 +23,19 @@ To understand what the result of amend will be I use the two following aliases [#]_:: - # diff what amend will look likes + # diff what amend will look like pdiff=diff --rev .^ - # status what amend will look likes + # status what amend will look like pstatus=status --rev .^ -It takes various options to pick an author, a date and the branch of the -result... (see ``hg help amend`` for details). +It takes various options to pick an author, a date, and the branch of the +result (see ``hg help amend`` for details). -This command can even be invoked on changesets with children (provided -none is public) ! +This command can even be invoked on changesets with children, provided +none are public. -.. note:: the amend command is very similar to mq's ``qrefresh``, a ``refresh`` +.. note:: As the amend command is very similar to mq's ``qrefresh``, a ``refresh`` alias for amend is also available. But note that contrary to ``qrefresh``, ``amend`` does not exclude changes on file not specified on the command line. @@ -50,7 +50,7 @@ Move a changeset: ``graft`` ------------------------------------------------------------ -The graft command introduced in 2.0 allows to "copy changes from other +The graft command introduced in 2.0 allows you to "copy changes from other branches onto the current branch". The graft command has been altered to allow the creation of an @@ -81,19 +81,18 @@ ------------------------------------------------------------ While working on mutable part of the history you often need to move between -mutable commit. +mutable commits. You just need to use standard update to work with evolve. For convenience, you -can use ``hg gup`` to move to children commit or ``hg gdown`` to move to working -directory parent commit. +can use ``hg gup`` to move to the child commit or ``hg gdown`` to move to the parent commit. -.. note:: those command only exist for the convenience of getting qpush and qpop +.. note:: Those commands only exist for the convenience of getting qpush and qpop feeling back. Collapse changesets: ``fold`` ------------------------------------------------------------ -you can use ``hg fold`` to collapse multiple changesets in a single one. +You can use ``hg fold`` to collapse multiple changesets in a single one. Getting changes out of a commit ------------------------------------------------------------ @@ -116,7 +115,7 @@ To split on file boundaries, just use ``uncommit`` command. -If you need fine-grained split, there is no official command for that yet. +If you need a fine-grained split, there is no official command for that yet. However, it is easily achieved by manual operation:: ### you want to split changeset A: 42 @@ -132,7 +131,7 @@ # current changeset (.) and previous one (.^) replace A (42) $ hg prune --new . --new .^ 42 -For more complexe scenario we recommand the use of the histedit_ extension. +For more complexe scenario we recommend the use of the histedit_ extension. .. _histedit:: http://mercurial.selenic.com/wiki/HisteditExtension @@ -143,7 +142,7 @@ Whenever you are working on some changesets, it is more likely that a pull will, eventually, import new changesets in your tree. -And it is likely that you will want your work in progress changiesets to be +And it is likely that you will want your work in progress changesets to be rebased on the top of this newly imported subtree. Doing so is only a matter of rebasing.
--- a/docs/evolve-good-practice.rst Thu Jan 24 18:02:00 2013 -0500 +++ b/docs/evolve-good-practice.rst Thu Jan 24 18:05:59 2013 -0500 @@ -2,7 +2,7 @@ .. Logilab SA <contact@logilab.fr> ----------------------------------------- -Good pratice for (early) user of evolve +Good practice for (early) users of evolve ----------------------------------------- Avoid unstability @@ -16,12 +16,12 @@ Branch as much as possible -------------------------------- -This is not MQ, you are not constrainted to linear history. +This is not MQ; you are not constrained to linear history. Making a branch per independent branch will help you avoid unstability and conflict. -Rewrite you change only +Rewrite your changes only ------------------------------------------------ There is no descent conflict detection and handling right now. @@ -29,10 +29,10 @@ conflicts. Communicate with your fellow developers before trying to touch other people's work (which is a good pratice in any case). -Using multiple branch will help you to achieve this goal. +Using multiple branches will help you to achieve this goal. -Prefer pushing unstability than touching other people changeset ------------------------------------------------------------------- +Prefer pushing unstability to touching other people changesets +-------------------------------------------------------------- If you have children changesets from other people that you don't really care
--- a/docs/from-mq.rst Thu Jan 24 18:02:00 2013 -0500 +++ b/docs/from-mq.rst Thu Jan 24 18:05:59 2013 -0500 @@ -39,7 +39,7 @@ phase revset to display unfinished work only, and use templates to have the same kind of compact that the output of qseries has. -This will result in something like that:: +This will result in something like:: [alias] wip = log -r 'not public()' --template='{rev}:{node|short} {desc|firstline}\n' @@ -49,7 +49,7 @@ With evolve you handle standard changesets without an additional overlay. -Standard changeset are created using hg commit as usual.:: +Standard changeset are created using hg commit as usual:: $ hg commit @@ -57,7 +57,7 @@ set your changeset in the secret phase using the phase command. Note that you only need it for the first commit you want to be secret. Later -commits will inherit their parents phase. +commits will inherit their parent's phase. If you always want your new commit to be in the secret phase, your should consider updating your configuration: @@ -92,7 +92,7 @@ hg qref --exclude ````````````````````` -To remove changes from you current commit use:: +To remove changes from your current commit use:: $ hg uncommit not-ready.txt @@ -100,7 +100,7 @@ hg qpop ````````` -The following command emulate the behavior of hg qpop: +The following command emulates the behavior of hg qpop: $ hg gdown @@ -108,8 +108,8 @@ $ hg update -.. note:: gdown and update allow movement with working directory changes applied - and gracefully merge them. +.. note:: gdown and update allow movement with working directory + changes applied, and gracefully merge them. hg qpush ```````` @@ -153,15 +153,15 @@ hg qdiff ````````` -``pdiff`` is an alias for `hg diff -r .^` it works as qdiff, but outside mq. +``pdiff`` is an alias for `hg diff -r .^` It works like qdiff, but outside MQ. hg qfinish and hg qimport ```````````````````````````` -These are not necessary anymore. If you want to control exchange and -mutability of changesets, see the phase feature +These are not necessary anymore. If you want to control the +mutability of changesets, see the phase feature.
--- a/docs/index.rst Thu Jan 24 18:02:00 2013 -0500 +++ b/docs/index.rst Thu Jan 24 18:05:59 2013 -0500 @@ -9,7 +9,7 @@ Here are various materials on planned improvement to Mercurial regarding rewriting history. -First read about what challenge arise while rewriting history and how we plan to +First, read about what challenges arise while rewriting history and how we plan to solve them once and for all. .. toctree:: @@ -20,10 +20,10 @@ The effort is split in two parts: * The **obsolescence marker** concept aims to provide an alternative to ``strip`` - to get rid of changesets. This concept have been partially implemented since + to get rid of changesets. This concept has been partially implemented since Mercurial 2.3. - * The **evolve** mercurial extension rewrites history using obsolete + * The **evolve** Mercurial extension rewrites history using obsolete *marker* under the hood. The first and most important step is by far the **obsolescence marker**. However @@ -34,35 +34,35 @@ ==================================== Evolve is an experimental history rewriting extension that uses obsolete -markers. It is inspired from MQ and pbranch but have multiple advantages over +markers. It is inspired by MQ and pbranch but has multiple advantages over them: * Focus on your current work. You can focus your work on a single changeset and take care of adapting - descendent changeset later. + descendent changesets later. * Handle **non-linear history with branches and merges** -* Rely internally on **robust merge** mechanism of mercurial. +* Rely internally on Mercurial's **robust merge** mechanism. - Simple conflict are handled by real merge tools using appropriate ancestor. - Conflict are much rarer and much more user friendly. + Simple conflicts are handled by real merge tools using the appropriate ancestor. + Conflicts are much rarer and much more user friendly. * Mutable history **fully available all the time**. - always use 'hg update' and forget about (un)applying patches to access the + Always use 'hg update' and forget about (un)applying patches to access the mutable part of your history. -* Use only **plain changeset** and forget about patches. Evole will create and +* Use only **plain changesets** and forget about patches. Evolve will create and exchange real changesets. Mutable history can be used in all usual operations: pull, push, log, diff, etc. -* Allow **sharing and collaboration** mutable history without fear of duplicate +* Allow **sharing and collaboration** mutable history without fear of duplicates (thanks to obsolete marker). -* Cover all mq usage but guard. +* Cover all MQ usage but guard. .. warning:: The evolve extension and obsolete markers are at an experimental stage. While using obsolete you willl likely be exposed to complex @@ -70,15 +70,15 @@ non-power users to test this at this stage. While numbered 1.0.0, the command line API of this version should - **not** be regarded as *stable*, command behavior, name and - options may change in future release or once integrated in - mercurial. It is still an immature extension, a lot of - features are still missing but there is no high risk of + **not** be regarded as *stable*: command behavior, name and + options may change in future releases or once integrated into + Mercurial. It is still an immature extension; a lot of + features are still missing but there is low risk of repository corruption. - Production ready version should hide such details to normal user. + Production-ready version should hide such details from normal users. -The evolve extension requires mercurial 2.4 (older version supports 2.3 and 2.2) +The evolve extension requires Mercurial 2.4 (older versions support 2.3 and 2.2) To enable the evolve extension use:: @@ -93,7 +93,7 @@ --- -For more information see documents below: +For more information see the documents below: .. toctree:: :maxdepth: 1 @@ -108,27 +108,27 @@ Smart changeset deletion: Obsolete Marker ========================================== -Obsolete marker is a powerful concept that allow mercurial to safely handle +The obsolete marker is a powerful concept that allows Mercurial to safely handle history rewriting operations. It is a new type of relation between Mercurial -changesets that track the result of history rewriting operations. +changesets that tracks the result of history rewriting operations. -This concept is simple to define and provides a very solid base to: +This concept is simple to define and provides a very solid base for: -- Very fast history rewriting operations, +- very fast history rewriting operations -- auditable and reversible history rewriting process, +- auditable and reversible history rewriting process -- clean final history, +- clean final history -- share and collaborate on mutable parts of the history, +- share and collaborate on mutable parts of the history -- gracefully handle history rewriting conflicts, +- gracefully handle history rewriting conflicts -- allow various history rewriting UI to collaborate with a underlying common API. +- allow various history rewriting UI to collaborate with a underlying common API --- -For more information see documents below +For more information, see the documents below .. toctree:: :maxdepth: 1 @@ -138,22 +138,22 @@ obs-implementation -Known limitation and bug +Known limitations and bugs ================================= -Here is a list of know issue that will be fixed later: +Here is a list of known issues that will be fixed later: -* you need to provide to `graft --continue -O` if you started you +* You need to provide to `graft --continue -O` if you started you graft using `-O`. you to manually specify target all the time. -* trying to exchange obsolete marker with a static http repo will crash. +* Trying to exchange obsolete marker with a static http repo will crash. * Extinct changesets are hidden using the *hidden* feature of mercurial only supported by a few commands. - Only ``hg log``, ``hgview`` and `hg glog` support it. ``hg head`` or other visual viewer don't. + Only ``hg log``, ``hgview`` and `hg glog` support it. Neither ``hg heads`` nor other visual viewers do. -* hg heads show extinct changeset +* hg heads shows extinct changesets.
--- a/docs/instability.rst Thu Jan 24 18:02:00 2013 -0500 +++ b/docs/instability.rst Thu Jan 24 18:05:59 2013 -0500 @@ -12,7 +12,7 @@ XXX starts by talking about getting ride of changeset. -DVCSes bring two new major concepts to the Version Control Scene: +DVCSes bring two new major concepts to the version control scene: * History is organized as a robust DAG, * History can be rewritten. @@ -23,13 +23,13 @@ * Full snapshot of the versioned content, * Reference to the previous full snapshot used to build the new one, - * A description of the change who lead from the old content to the new old. + * A description of the change which leads from the old content to the new content. -All three elements are to compute a *unique* hash that identify the changeset +All three elements are used to compute a *unique* hash that identifies the changeset (with various other metadata). This identification is a key part of DVCS design. -This is a very useful property because Changing B parent means -changing B content too. This requires the creation of **another** +This is a very useful property because changing B's parent means +changing B's content too. This requires the creation of **another** changeset, which is semantically good. .. figure:: ./figures/edit-is-rewrite-step2.svg @@ -39,30 +39,30 @@ history. I'm calling them *obsolete* changesets. -But rewriting a changeset with children does not change these -children's parent! And because children of the rewritten changeset -still **depend** on the older "dead" version of the changeset with -can not get rid of this dead version. +But rewriting a changeset with children does not change the +children's parents! And because children of the rewritten changeset +still **depend** on the older "dead" version of the changeset, we +cannot get rid of this dead version. :: Schema base, A and A' and B. I'm calling these children **unstable** because they are based on a -dead changeset and prevent people to get rid of it. +dead changeset and prevent people from getting rid of it. This instability is an **unavoidable consequence** of the strict dependency of -changeset. History Rewriting history alway need to take it in account and -provide a way to rewrite the descendant on the new changeset to avoid -coexistence of the old and new version of a rewritten changeset. +changesets. Rewriting history always needs to take it into account and +provide a way to rewrite the descendants of the new changeset to avoid +coexistence of the old and new versions of a rewritten changeset. Everybody is working around the issue ------------------------------------------------ -I'm not claiming that rewriting history is impossible. People are successfully -doing for years. However they all need to work around *instability*. Several -work around strategy exists. +I'm not claiming that rewriting history is impossible. People have been successfully +doing it for years. However they all need to work around *instability*. Several +workaround strategies exist. Rewriting all at once @@ -79,17 +79,17 @@ Schema! Several Mercurial commands apply it: rebase, collapse, histedit. -Mercurial also refuses to amend changeset with descendant. The git -branch design enforces such approach in git too. +Mercurial also refuses to amend changesets with descendants. The git +branch design enforces this approach in git too. -However, DVCS are **Distributed**. This means that you do not control what -happen outside your repository. Once a changeset have been exchanged *outside*, +However, DVCS are **distributed**. This means that you do not control what +happens outside your repository. Once a changeset has been exchanged *outside*, there is no way to be sure it does not have descendants somewhere else. Therefore **if you rewrite changeset that exists elsewhere, you can't eradicate the risk of instability.** -Do not rewrite exchanged changeset +Do not rewrite exchanged changesets ``````````````````````````````````` To work around the issue above, Mercurial introduced phases, which @@ -99,13 +99,13 @@ collaborating on mutable changesets. In the Git world, they use another approach to prevent instability. By -convention only a single developper works on a changeset contained in +convention only a single developer works on a changeset contained in a named branch. But once again this is a huge blocker for collaborating. Moreover clueless people **will** mess up social convention soon or later. -Loose the DAG robustness +Lose the DAG robustness ```````````````````````````` The other approach in Mercurial is to keep the mutable part of the @@ -115,15 +115,15 @@ This allow much more flexible workflow but two major feature are lost in the process: -:graceful merge: MQ use plain-patch to store changeset content and patch have - trouble to apply in changing context. Applying your queue +:graceful merge: MQ uses plain patch to store changeset contents, which has + problems in changing context. Applying your queue becomes very painful when context changes. -:easy branching: A quilt queue is by definition a linear queue. Increasing risk - of conflict +:easy branching: A quilt queue is by definition a linear queue, increasing risk + of conflict. -It is possible to collaborate over versioned mq! But you are going to -have a lot of troubles. +It is possible to collaborate over versioned MQ! But you are going to +have a lot of trouble. Ignore conflicts ``````````````````````````````````` @@ -137,28 +137,28 @@ The "One set of mutable changset == One developer" mantra is also a way to work around conflicting rewriting of changeset. If two different people are able to -The git branch model allow to overwrite changeset version by another +The git branch model allows overwriting changeset version by another one, but it does not care about divergent version. It is the equivalent of "common ftp" source management for changesets. Facing The Danger Once And For All ------------------------------------------------ -Above we saw that, the more effort you put to avoid instability, the more option -you deny. And even most restrictive work flow can't guarantee that instability +Above we saw that the more effort you put to avoid instability, the more options +you deny. And even the most restrictive workflow can't guarantee that instability will never show up! Obsolete marker can handle the job ``````````````````````````````````` -It is time to provide a full featured solution to deal with +It is time to provide a full-featured solution to deal with instability and to stop working around the issue! This is why I -developing a new feature for mercurial called "Obsolete markers". +am developing a new feature for Mercurial called "Obsolete markers". Obsolete markers have two key properties: -* Any "old" changeset we want to get ride of is **explicitly** marked - as "obsolete" by history rewriting operation. +* Any "old" changeset we want to get rid of is **explicitly** marked + as "obsolete" by history rewriting operations. By explicitly marking the obsolete part of the history, we will be able to easily detect instability situation. @@ -166,18 +166,18 @@ * Relations between old and new version of changesets are tracked by obsolete markers. - By Storing a meta-history of changeset evolution we are able to easily resolve - instability and edition conflict [#]_ . + By storing a meta-history of changeset evolution we are able to easily resolve + instability and edit conflicts [#]_ . -.. [#] edition conflict is another major obstable to collaboration. See the +.. [#] Edit conflicts is another major obstable to collaboration. See the section dedicated to obsolete marker for details. -Improves robustness == improves simplicity +Improved robustness == improved simplicity ```````````````````````````````````````````````` This proposal should **first** be seen as a safety measure. -It allow to detect instability as soon as possible +It allows detecting instability as soon as possible. :: @@ -190,7 +190,7 @@ outgoing unstable changesets (use "hg evolve" or force the push) -And should not not encourage people to create instability +And it should not not encourage people to create instability. ::
--- a/docs/qsync.rst Thu Jan 24 18:02:00 2013 -0500 +++ b/docs/qsync.rst Thu Jan 24 18:05:59 2013 -0500 @@ -6,10 +6,10 @@ --------------------------------------------------------------------- -People may have tools or co-workers that export to receive mutable history using -a versioned mq repository. +People may have tools or co-workers that expect to receive mutable history using +a versioned MQ repository. -For this purpose you can use the ``qsync`` extension: +For this purpose you can use the ``qsync`` extension. To enable the evolve extension use::