From 190d8265478b9c69bced02f9d34cdbdc5da54635 Mon Sep 17 00:00:00 2001 From: Jonas Bernoulli Date: Thu, 6 Jun 2024 00:09:01 +0200 Subject: [PATCH] manual: Copyedit --- docs/forge.org | 131 +++++++++++++++++++++++++------------------------ 1 file changed, 66 insertions(+), 65 deletions(-) diff --git a/docs/forge.org b/docs/forge.org index 56ba86ea..7dca02ea 100644 --- a/docs/forge.org +++ b/docs/forge.org @@ -51,7 +51,7 @@ and additional hosts can easily be supported by adding entries to the option ~forge-alist~ (see [[*Repository Detection]]). For more details about the caveats mentioned below (and some others) -also see [[*Getting Started]]. +see also [[*Getting Started]]. ** Supported Forges *** Github @@ -60,7 +60,7 @@ also see [[*Getting Started]]. :END: Forge's support for Github can be considered the "reference - implementation". Support for other forges can lag behind a bit. +implementation". Support for other forges can lag behind a bit. **** Github Caveats @@ -254,9 +254,9 @@ documented in [[info:ghub#Getting Started]]. Ghub used to provide a setup wizard, but that had to be removed for reasons given in the manual just mentioned. Nowadays there is no way -around reading the documentation and doing this manually I am afraid. +around reading the documentation and doing this manually, I am afraid. - Forge requires the following token scopes. +Forge requires the following token scopes. - For Github these scopes are required. @@ -275,22 +275,23 @@ around reading the documentation and doing this manually I am afraid. ** Initial Pull -To start using Forge in a certain repository visit the Magit status -buffer for that repository and type ~f n~ (~forge-pull~). Alternatively, -you can use ~M-x forge-add-repository~, which makes it possible to add a -forge repository without pulling all topics and even without having to -clone the respective Git repository. - You must set up a token *before* you can add the first repository. See [[*Token Creation]]. -The first time ~forge-pull~ is run in a repository, an entry for that -repository is added to the database and a new value is added to the -Git variable ~remote..fetch~, which fetches all pull-requests. -(~+refs/pull/*/head:refs/pullreqs/*~ for Github) +After that, to start using Forge in a certain repository visit the +Magit status buffer for that repository and type ~N / a~ +(~forge-add-repository~). You are given a choice to pull all topics, +all topics that were updated after a certain date, or only individual +topics. + +Beside adding the repository to the database, this also adds a new +value to the Git variable ~remote..fetch~, which causes all +pull-request refs (~+refs/pull/*/head:refs/pullreqs/*~ for Github) +to be fetched by Git. -~forge-pull~ then fetches topics and other information using the forge's -API and pull-request references using Git. +Note that it is possible to add a repository to the database, without +cloning the Git repository first. The entry point is the same as +described above. The initial fetch can take a while but most of that is done asynchronously. Storing the information in the database is done @@ -298,7 +299,7 @@ synchronously though, so there can be a noticeable hang at the end. Subsequent fetches are much faster. Fetching issues from Github is much faster than fetching from other -forges because making a handful of GraphQL requests is much faster +forges, because making a handful of GraphQL requests, is much faster than making hundreds of REST requests. ** Repository Detection @@ -306,11 +307,11 @@ than making hundreds of REST requests. Ghub does *not* associate a given local repository with a repository on a forge. The Forge package itself takes care of this. In doing so it ignores the Git variable ~ghub.host~ and other ~*.host~ variables used by -Ghub. (But ~github.user~ and other variables used to specify the user +Ghub. (But ~github.user~, and other variables used to specify the user, are honored). -Forge associates the local repository with a forge repository by first -determining which remote is associated with the upstream repository +Forge associates the local repository with a forge repository, by first +determining which remote is associated with the upstream repository, and then looking that up in ~forge-alist~. If only one remote exists, then Forge uses that unconditionally. To @@ -330,8 +331,8 @@ Note, however, that even though a surprising number of people do just that, it does not make any sense to use the name "origin" to refer to a fork; not even to your own fork. A fork is a *copy* of the original, "copy" is an antonym for "original", and the word "origin" is not only -closely related to but even contained in the word "original". Naming -a fork the "origin" is at best extremely confusing. +closely related to but is even contained in the word "original". +Naming a fork the "origin" is at best extremely confusing. - copy :: a thing made to be similar or identical to another. @@ -381,13 +382,14 @@ which case "upstream" must be preferred). This command changes the value of the ~forge.remote~ Git variable in the current repository. +TODO is this still accurate? If this variable is set, then Forge uses the remote by that name, if -it exists, the same way it may have used ~origin~ if the the variable -were undefined. I.e., it does not fall through to try ~origin~ if no -remote by your chosen name exists. +it exists, the same way it may have used ~origin~ if the variable were +undefined. I.e., it does not fall through to try ~origin~ if no remote +by your chosen name exists. Once the upstream remote has been determined, Forge looks it up in -~forge-alist~, using the host part of the URL as the key. For example +~forge-alist~, using the host part of the URL as the key. For example, the key for ~git@github.com:magit/forge.git~ is ~github.com~. - User Option: forge-alist :: @@ -423,16 +425,16 @@ the key for ~git@github.com:magit/forge.git~ is ~github.com~. ** Caveats - Fetched information is stored in a database. The table schemata of - that database have not been finalized yet. Until that has happened - it will occasionally have to be discarded. That isn't such a huge - deal because for now the database does not contain any information - that cannot simply be fetched again, see [[*Initial Pull]]. + that database have not been finalized yet. So far it was possible + to automatically update existing databases to new schemata, but + there soon will come a day, when I have to make more drastic changes + to address the accumulated deficiencies. - Fetching is implemented under the assumption that the API can be asked to list the things that have changed since we last checked. Unfortunately the APIs are not bug-free, so this is not always the - case. If in doubt, then re-fetch an individual topic to ensure it - is up-to-date using the command ~forge-pull-topic~. + case. If in doubt, you can re-fetch an individual topic to ensure + it is up-to-date, using the command ~forge-pull-topic~. - Some other, forge-specific, caveats are mentioned in [[*Supported Forges and Hosts]]. @@ -445,11 +447,11 @@ and "Issues" to Magit's status buffer. It is also possible to add a repository to the local database without pulling all the data, which is useful if you want to create a single pull-request. -- Key: N a (forge-add-repository) :: +- Key: N / a (forge-add-repository) :: This command adds a repository to the database. - It offers to either pull topics (now and in the future) or to only + It offers to either pull topics (now and in the future) or to only UPDATE pull individual topics when the user invokes ~forge-pull-topic~. Some of Forge's commands are only bound when point is within one of @@ -469,30 +471,31 @@ Magit's status buffer and/or from Magit's transient commands. ** Pulling -The commands that fetch forge data are available from the same -transient prefix command (~magit-fetch~ on ~f~) that is used to fetch Git -data. If option ~magit-pull-or-fetch~ is non-nil, then they are also -available from the ~magit-pull~ transient (on ~F~). +The commands that fetch forge data, are available from the same +transient prefix command (~magit-fetch~ on ~f~), which is used to fetch +Git data. If option ~magit-pull-or-fetch~ is non-nil, then they are +also available from the ~magit-pull~ transient (on ~F~). - Key: f n (forge-pull) :: - Key: N f f :: This command uses a forge's API to fetch topics and other - information about the current repository and stores the fetched - information in the database. It also fetches notifications for all - repositories from the same forge host. (Currently this is limited - to Github.) Finally it fetches pull-request references using Git. + information about the current repository, and stores the fetched + information in the local database. It also fetches notifications + for all repositories from the same forge host. (Currently this is + limited to Github.) Finally, it fetches pull-request references + using Git. - After using this command for the first time in a given repository - the status buffer for that repository always lists the pull-requests - and issues. See [[*Initial Pull]]. + After using this command for the first time in a given repository, + the status buffer for that repository lists its open and/or pending + pull-requests and issues. See [[*Initial Pull]]. - Key: f N (forge-pull-notifications) :: - Key: N f n :: This command uses a forge's API to fetch all notifications from that - forge including, but not limited to, the notifications for the current - repository. + forge, including, but not limited to, the notifications for the + current repository. Fetching all notifications fetches associated topics even if you have not started fetching *all* topics for the respective repositories @@ -500,27 +503,24 @@ available from the ~magit-pull~ transient (on ~F~). the status buffer of such "uninitialized" repositories. Note how pulling data from a forge's API works the same way as pulling -Git data does; you do it explicitly when you want to see the work done +Git data does; you do it explicitly, when you want to see the work done by others. -This is less disruptive, more reliable, and easier to understand than +This is less disruptive, more reliable, and easier to understand, than if Forge did the pulling by itself at random intervals. It might -however mean that you occasionally invoke a command expecting the most -recent data to be available and then have to abort to pull first. -The same can happen with Git, e.g., you might attempt to merge a branch -that you know exists but haven't actually pulled yet. +however mean, that you occasionally invoke a command, expecting the +most recent data to be available, and then have to abort and pull +first. The same can happen with Git, e.g., you might attempt to merge +a branch, that you know exists, but haven't actually pulled yet. - Key: N f t (forge-pull-topic) :: - This command uses a forge's API to fetch a single pull-request and - stores it in the database. - - Normally you wouldn't want to pull a single pull-request by itself, - but due to a bug in the Github API you might sometimes have to do - so. + This command uses a forge's API to fetch a single topic and stores + it in the database. - Fetching is implemented under the assumption that the API can be - asked to list the things that have changed since we last checked. + TODO since with identical above + Fetching is implemented under the assumption, that the API can be + asked to list the things that have changed, since we last checked. Unfortunately the APIs are not bug-free, so this is not always the case. If in doubt, then re-fetch an individual topic to ensure it is up-to-date using the command ~forge-pull-topic~. @@ -529,7 +529,7 @@ that you know exists but haven't actually pulled yet. Forge provides commands for creating and checking out a new branch or work tree from a pull-request. These commands are available from the -same transient prefix commands as the suffix commands used to create +same transient prefix commands as the suffix commands, used to create and check out branches and work trees in a more generic fashion (~magit-branch~ on ~b~ and ~magit-worktree~ on ~%~). @@ -627,11 +627,11 @@ and check out branches and work trees in a more generic fashion This command creates and configures a new branch from a pull-request the same way ~forge-branch-pullreq~ does. Additionally it checks out - the new branch using a new working tree. + the new branch, using a new working tree. - User Option: forge-checkout-worktree-read-directory-function :: - This function is used by ~forge-checkout-worktree~ to read the new + This function is used by ~forge-checkout-worktree~, to read the new worktree directory where it checks out the pull-request. It takes the pull-request as the only argument and must return a directory. @@ -645,6 +645,7 @@ Note that you have to delete the local branch (e.g., "feature") for this to work. If you delete the tracking branch (e.g., "fork/feature"), then the remote is never removed. +TODO continue here ** Working with Topics We call both issues and pull-requests "topics". The contributions to @@ -961,7 +962,7 @@ The following commands are available in buffers used to edit posts: :APPENDIX: t :END: -This section lists some frequently asked questions. Please also see +This section lists some frequently asked questions. Please see also https://github.com/magit/forge/wiki/FAQ for an extended list of common issues.