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.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...
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@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
