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.demar...@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... > +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," ... > +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... > For development you should rather and change tone to recommended... > + use the DIM_REPO directory after calling the create-workdir command. or create another branch workdir like dev?! > > -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... > + > +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@lists.freedesktop.org > https://lists.freedesktop.org/mailman/listinfo/dim-tools _______________________________________________ dim-tools mailing list dim-tools@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/dim-tools
