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 <[email protected]> --- 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 +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 +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. For development you should rather + use the DIM_REPO directory after calling the create-workdir command. -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. + +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 [email protected] https://lists.freedesktop.org/mailman/listinfo/dim-tools
