docs/repository.rst

   1 Source Code Repository
   2 ======================
   3
   4 Mesa uses `git <https://git-scm.com>`__ as its source code management
   5 system.
   6
   7 The master git repository is hosted on
   8 `freedesktop.org <https://www.freedesktop.org>`__.
   9
  10 You may access the repository either as an :ref:`anonymous
  11 user <anonymous>` (read-only) or as a :ref:`developer <developer>`
  12 (read/write).
  13
  14 You may also `browse the main Mesa git
  15 repository <https://gitlab.freedesktop.org/mesa/mesa>`__ and the `Mesa
  16 demos and tests git
  17 repository <https://gitlab.freedesktop.org/mesa/demos>`__.
  18
  19 .. _anonymous:
  20
  21 Anonymous git Access
  22 --------------------
  23
  24 To get the Mesa sources anonymously (read-only):
  25
  26 #. Install the git software on your computer if needed.
  27 #. Get an initial, local copy of the repository with:
  28
  29    ::
  30
  31       git clone https://gitlab.freedesktop.org/mesa/mesa.git
  32
  33 #. Later, you can update your tree from the master repository with:
  34
  35    ::
  36
  37       git pull origin
  38
  39 #. If you also want the Mesa demos/tests repository:
  40
  41    ::
  42
  43       git clone https://gitlab.freedesktop.org/mesa/demos.git
  44
  45 .. _developer:
  46
  47 Developer git Access
  48 --------------------
  49
  50 If you wish to become a Mesa developer with gitlab merge privilege,
  51 please follow this procedure:
  52
  53 #. Subscribe to the
  54    `mesa-dev <https://lists.freedesktop.org/mailman/listinfo/mesa-dev>`__
  55    mailing list.
  56 #. Start contributing to the project by :doc:`submitting
  57    patches <submittingpatches>`. Specifically,
  58
  59    -  Use `gitlab <https://gitlab.freedesktop.org/>`__ to create your
  60       merge requests.
  61    -  Wait for someone to review the code and give you a ``Reviewed-by``
  62       statement.
  63    -  You'll have to rely on another Mesa developer to push your initial
  64       patches after they've been reviewed.
  65
  66 #. After you've demonstrated the ability to write good code and have had
  67    a dozen or so patches accepted, a maintainer may use their discretion
  68    to give you access to merge your own code.
  69
  70 Pushing code to your gitlab account via HTTPS
  71 ---------------------------------------------
  72
  73 Useful for people behind strict proxies
  74
  75 You can use `personal access
  76 tokens <https://gitlab.freedesktop.org/profile/personal_access_tokens>`__
  77 to push over HTTPS if ssh will does not suit your needs. In this case,
  78 create a token, and put it in the url as shown here:
  79
  80 ::
  81
  82    git remote set-url --push origin https://USER:TOKEN@gitlab.freedesktop.org/your~user~name/mesa.git
  83
  84 Windows Users
  85 -------------
  86
  87 If you're `using git on
  88 Windows <https://git.wiki.kernel.org/index.php/WindowsInstall>`__ you'll
  89 want to enable automatic CR/LF conversion in your local copy of the
  90 repository:
  91
  92 ::
  93
  94    git config --global core.autocrlf true
  95
  96 This will cause git to convert all text files to CR+LF on checkout, and
  97 to LF on commit.
  98
  99 Unix users don't need to set this option.
 100
 101 Development Branches
 102 --------------------
 103
 104 At any given time, there may be several active branches in Mesa's
 105 repository. Generally, ``master`` contains the latest development
 106 (unstable) code while a branch has the latest stable code.
 107
 108 The command ``git branch`` will list all available branches.
 109
 110 Questions about branch status/activity should be posted to the mesa-dev
 111 mailing list.
 112
 113 Developer Git Tips
 114 ------------------
 115
 116 #. Setting up to edit the master branch
 117
 118    If you try to do a pull by just saying\ ``git pull`` and git
 119    complains that you have not specified a branch, try:
 120
 121    ::
 122
 123       git config branch.master.remote origin
 124       git config branch.master.merge master
 125
 126    Otherwise, you have to say\ ``git pull origin master`` each time you
 127    do a pull.
 128
 129 #. Small changes to master
 130
 131    If you are an experienced git user working on substantial
 132    modifications, you are probably working on a separate branch and
 133    would rebase your branch prior to merging with master. But for small
 134    changes to the master branch itself, you also need to use the rebase
 135    feature in order to avoid an unnecessary and distracting branch in
 136    master.
 137
 138    If it has been awhile since you've done the initial clone, try
 139
 140    ::
 141
 142       git pull
 143
 144    to get the latest files before you start working.
 145
 146    Make your changes and use
 147
 148    ::
 149
 150       git add <files to commit>
 151       git commit
 152
 153    to get your changes ready to push back into the fd.o repository.
 154
 155    It is possible (and likely) that someone has changed master since you
 156    did your last pull. Even if your changes do not conflict with their
 157    changes, git will make a fast-forward merge branch, branching from
 158    the point in time where you did your last pull and merging it to a
 159    point after the other changes.
 160
 161    To avoid this,
 162
 163    ::
 164
 165       git pull --rebase
 166       git push
 167
 168    If you are familiar with CVS or similar system, this is similar to
 169    doing a ``cvs update`` in order to update your source tree to the
 170    current repository state, instead of the time you did the last
 171    update. (CVS doesn't work like git in this respect, but this is
 172    easiest way to explain it.)
 173
 174    In any case, your repository now looks like you made your changes
 175    after all the other changes.
 176
 177    If the rebase resulted in conflicts or changes that could affect the
 178    proper operation of your changes, you'll need to investigate those
 179    before doing the push.
 180
 181    If you want the rebase action to be the default action, then
 182
 183    ::
 184
 185       git config branch.master.rebase true
 186       git config --global branch.autosetuprebase=always
 187
 188    See `Understanding Git
 189    Conceptually <https://www.eecs.harvard.edu/~cduan/technical/git/>`__
 190    for a fairly clear explanation about all of this.