[PATCH 2/2] doc: restructure Getting Started page

Fri Mar 8 22:31:14 UTC 2019

On Fri, Mar 08, 2019 at 02:14:03PM -0800, Rodrigo Vivi wrote:
>On Tue, Mar 05, 2019 at 11:44:00AM -0800, Lucas De Marchi wrote:
>> Restructure this pages so it first gives a minimal set of commands to
>> get the environment setup and then explains the other parts. We
>> tailor the commands so the user already clones the maintainer-tools
>> repository in the right place, avoiding additional explanations and
>> steps.
>>
>> The paragraphs were reordered and reworded a little bit so it follows
>> the flow "zero -> contributor -> committer -> maintainer".
>>
>> Signed-off-by: Lucas De Marchi <lucas.demarchi at intel.com>
>> ---
>>  getting-started.rst | 68 ++++++++++++++++++++++++++-------------------
>>  1 file changed, 39 insertions(+), 29 deletions(-)
>>
>> diff --git a/getting-started.rst b/getting-started.rst
>> index 5d4ce9c..d6f66f1 100644
>> --- a/getting-started.rst
>> +++ b/getting-started.rst
>> @@ -4,54 +4,63 @@
>>   Getting Started
>>  =================
>>
>> -For getting started grab the latest dim (drm-intel-maintainer) script from::
>> +For getting started grab use the latest dim (drm-intel-maintainer) script to
>
>It's a bit strange here... (grab use)
>
>Maybe:
>For getting started, use the...

The intention was indeed to replace the verb.

>
>> +setup your environment::
>>
>> -    https://gitlab.freedesktop.org/drm/maintainer-tools/raw/master/dim
>> +    export DIM_PREFIX=/path/to/setup/the/project
>> +    cd $DIM_PREFIX
>> +    git clone https://gitlab.freedesktop.org/drm/maintainer-tools.git
>> +    ./maintainer-tools/dim setup
>>
>> -There's also a sample config file for ~/.dimrc::
>> -
>> -    https://gitlab.freedesktop.org/drm/maintainer-tools/raw/master/dimrc.sample
>> +Internally the script uses the :code:`DIM_PREFIX` environment variable to know
>> +where to setup all the repositories. You may want to set this in your
>> +:code:`$HOME/.dimrc`. A sample configuration file is available at
>> +https://gitlab.freedesktop.org/drm/maintainer-tools/raw/master/dimrc.sample.
>>
>>  Plus, there's bash completion in the same directory if you feel like using that.
>> -Run::
>> +For the commands below we assume the :code:`dim` script is in your
>> +:code:`$PATH`. Run::
>>
>>      $ dim help
>>
>> -for tons of details about how this thing works. Also see the git repository
>> -specific pages for details on the patch merging process for each tree. Adjust
>> -your .dimrc to match your setup and then run::
>> -
>> -    $ dim setup
>> +for tons of details about how this thing works. By cloning the maintainer-tools
>> +repository inside :code:`$DIM_PREFIX` like above you will keep it in sync
>
>I'm bad with commas in en or even in pt-br, but I believe some comma is missing
>here..
>
>maybe: ", like above," ...

ok

>
>> +together with all other repositories whenever you call::
>>
>> -This will also check out the latest maintainer-tools branches, so please replace
>> -the dim you just downloaded with a symlink after this step. And by the way, if
>> -you have improvements for dim, see `contributing
>> -<dim.html#contributing-bug-reports-and-discussion>`_.
>> +    $ dim update-branches
>>
>>  If you have a freedesktop.org account and plan to push things on one of the
>>  drm-xxx repos, you should use the ssh://git.freedesktop.org/git/drm-xxx urls
>> -when adding a remote. Note that dim will ask you to add missing remotes
>> -automatically, and by default uses the ssh:// url format. To make these urls
>> -without login names work, you should add a new entry in ~/.ssh/config, if that's
>> -not yet configured::
>> +when adding a remote. Note that during the setup process dim will ask you to
>> +add missing remotes automatically, and by default uses the ssh:// url format.
>> +To make these urls without login names work, you should add a new entry in
>> +~/.ssh/config, if that's not yet configured::
>>
>>      $ printf '\nHost git.freedesktop.org\n\tUser <username>' >> ~/.ssh/config
>>
>>  You should now have a main repository for patch application. The directory
>> -corresponding to this repository is defined by DIM_REPO in your .dimrc.
>> -You should also have directories called maintainer-tools, drm-tip (for
>> -rebuilding the tree), and drm-rerere for some dim-internal book-keeping.
>> +corresponding to this repository is defined by DIM_REPO in your .dimrc and
>> +default to :code:`src/`. You should also have directories called
>> +maintainer-tools, drm-tip (for rebuilding the tree), and drm-rerere for some
>> +dim-internal book-keeping. It's highly recommended that you also call::
>> +
>> +    $ dim create-workdir
>> +
>>
>> -If someone else has pushed patches first resync using::
>> +.. note::
>>
>> -   $ dim update-branches
>> +    The drm-tip directory is internal to dim.
>
>I know what you meant here, but people new here might get confused by the way
>it is written. I mean, instead of using the word "internal" we could highlight
>that dim uses drm-tip directory to perform operations so any of work done
>here will be overwritten...

dim also fails miserably when pushing if you touch these.

>
>> For development you should rather
>
>and change tone to recommended...

ok

>
>> +    use the DIM_REPO directory after calling the create-workdir command.
>
>or create another branch workdir like dev?!

after you call create-workdir you are free to use src (or whatever name you
gave it during setup).

>
>>
>> -Since dim supports lots of different branches in different repositories you
>> -first need to check out the right branch using::
>> +
>> +It will create separate work directories for each branch. During development
>> +you should use DIM_REPO and work on top of the drm-tip branch.
>
>This probably doesn't work, because git will complain drm-tip is already
>checked out at drm-tip directory. This is the reason that I have a branch
>dev checked out to directory dev and I reset hard to drm-tip/drm-tip...

intention here is *not* to checkout drm-tip. It's to checkout
drm-tip/drm-tip and give a meaninful name for the local branch
like tip-my-awesome-feature, i.e.

git checkout -b tip-pll drm-tip/drm-tip

Lucas De Marchi

>
>> +
>> +To apply a patch on a specific you first need a up-to-date checkout::
>>
>>     $ dim checkout <branch>
>>
>> -Applying patches is done in the main repository with::
>> +Applying patches is done with::
>>
>>      $ cat patch.mbox | dim apply-branch <branch>
>>
>> @@ -72,6 +81,7 @@ can always use your every day tooling to get things done.
>>  For example, if a wrong patch was applied or you need to update commit message
>>  or fix anything else in the git repository, then just use git to do so
>>  as usual.
>> -
>> +
>>  Please subscribe to the https://lists.freedesktop.org/mailman/listinfo/dim-tools
>> -mailing list if you use dim.
>> +and if you have improvements for dim, see `contributing
>> +<dim.html#contributing-bug-reports-and-discussion>`_.
>> --
>> 2.20.1
>>
>> _______________________________________________
>> dim-tools mailing list
>> dim-tools at lists.freedesktop.org
>> https://lists.freedesktop.org/mailman/listinfo/dim-tools