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

Rodrigo Vivi rodrigo.vivi at intel.com
Fri Mar 8 22:36:43 UTC 2019


On Fri, Mar 08, 2019 at 02:31:14PM -0800, Lucas De Marchi wrote:
> 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

oh! drm-tip/drm-tip of course!
duh!

> 
> 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
> _______________________________________________
> dim-tools mailing list
> dim-tools at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dim-tools


More information about the dim-tools mailing list