| |
@@ -3,7 +3,7 @@
|
| |
Getting started with SSSD
|
| |
=========================
|
| |
|
| |
- This document will describe the step-by-step to "How to make your first
|
| |
+ This document is a step-by-step guide for "How to make your first
|
| |
contribution to SSSD project".
|
| |
|
| |
Setting up an environment for development
|
| |
@@ -55,40 +55,49 @@
|
| |
dnssec-validation no;
|
| |
|
| |
- Restart the named-pkcs11.service:
|
| |
- ``sudo systemctl restart named-pkcs11.service``
|
| |
+ ``$ sudo systemctl restart named-pkcs11.service``
|
| |
|
| |
GitHub workflow
|
| |
---------------
|
| |
|
| |
- SSSD is hosted on `pagure.io <https://pagure.io/SSSD/sssd>`_ but the
|
| |
- development happens on `GitHub <https://github.com/SSSD/sssd>`__.
|
| |
+ For general information about SSSD hosting see the paragraph
|
| |
+ `Source Code Repository <https://docs.pagure.org/SSSD.sssd/developers/contribute.html#source-code-repository>`__.
|
| |
+ It covers using SSSD's Pagure repository.
|
| |
|
| |
- So, the first thing to contribute to SSSD is forking our `GitHub
|
| |
- <https://github.com/SSSD/sssd>`__ repository.
|
| |
+ This section assumes you use GitHub.
|
| |
|
| |
- In order to do so, go to our `SSSD's github page
|
| |
- <https://github.com/SSSD/sssd>`__, log in with your GitHub account
|
| |
- and click in the ``Fork`` button. It will create a sssd fork in your
|
| |
- own GitHub account. Once it's done ...
|
| |
+ At first some general information. All pull request activity generates
|
| |
+ an e-mail notification to the `sssd-devel
|
| |
+ <https://docs.pagure.org/SSSD.sssd/developers/contribute.html#contribute>`__
|
| |
+ mailing list so that we keep the development history outside GitHub.
|
| |
+
|
| |
+ These are the steps to contribute to SSSD:
|
| |
+
|
| |
+ At first fork our GitHub repository. In order to do so, go to the
|
| |
+ `SSSD GitHub page <https://github.com/SSSD/sssd>`__, log in with
|
| |
+ your GitHub account and click on the ``Fork`` button. It will create
|
| |
+ a fork in your own GitHub account. Once it's done ...
|
| |
|
| |
- Clone your own SSSD fork:
|
| |
``$ git clone git@github.com:<your_username>/sssd.git``
|
| |
|
| |
- - Add `SSSD's github repo <https://github.com/SSSD/sssd>`__ as a
|
| |
- remote repo: ``$ git remote add github https://github.com/SSSD/sssd``
|
| |
+ - Add SSSD's GitHub repo as a remote repo:
|
| |
+ ``$ git remote add github https://github.com/SSSD/sssd``
|
| |
|
| |
+ Using ``https://`` will ensure you don't push to SSSD's GitHub repo by mistake.
|
| |
Once those two steps are done, you're good to go and start hacking on
|
| |
- your task. We strongly recommend to that in local branches!
|
| |
+ your task. We strongly recommend to do that in local branches!
|
| |
|
| |
- - Create your local branch: ``git checkout -b wip/meaningful_name``
|
| |
+ - Create your local branch:
|
| |
+ ``$ git checkout -b wip/meaningful_name``
|
| |
|
| |
Considering you have built SSSD following the instructions provided
|
| |
in our `Contribute page
|
| |
- <https://docs.pagure.org/SSSD.sssd/developers/contribute.html>`__ ,
|
| |
+ <https://docs.pagure.org/SSSD.sssd/developers/contribute.html>`__,
|
| |
have made your changes following our `Coding guidelines
|
| |
- <https://docs.pagure.org/SSSD.sssd/developers/coding_style.html>`__ and
|
| |
+ <https://docs.pagure.org/SSSD.sssd/developers/coding_style.html>`__,
|
| |
have committed your changes following our `git-commit-template
|
| |
- <https://github.com/SSSD/sssd/blob/master/.git-commit-template>`__ and
|
| |
+ <https://github.com/SSSD/sssd/blob/master/.git-commit-template>`__, and
|
| |
have implemented some unit/integration tests to ensure we're never hit
|
| |
by this very same issue again in the future ... now is time to open your
|
| |
pull-request.
|
| |
@@ -98,9 +107,12 @@
|
| |
- Push the changes to *your* SSSD repo:
|
| |
``$ git push origin wip/meaningful_name``
|
| |
|
| |
- - Go to your GitHub page;
|
| |
+ - Open the Pull Request either:
|
| |
|
| |
- - Open the Pull Request by using GitHub's web UI.
|
| |
+ - by using GitHub's web UI on your GitHub page, or
|
| |
+
|
| |
+ - by using the `hub <https://github.com/github/hub>`__ tool:
|
| |
+ ``$ hub pull-request``
|
| |
|
| |
Here, I'd like to add some really basic etiquette rules for opening the
|
| |
pull-request:
|
| |
@@ -114,14 +126,15 @@
|
| |
reproduce the issue you're fixing and/or to reproduce the feature
|
| |
you're implementing.
|
| |
|
| |
- Okay. Now your pull-request is opened and will be reviewed by one of
|
| |
+ Click on **[Create pull request]**.
|
| |
+ Now your pull-request has been created and will be reviewed by one of
|
| |
the core SSSD developers.
|
| |
|
| |
- Please, keep in mind that as the most part of the developers may also
|
| |
- be quite busy with their day-to-day job and may take some time till
|
| |
- someone actually review your pull-request. Sending a "ping"/"bump" is
|
| |
+ Please, keep in mind that the developers may also
|
| |
+ be quite busy with their day-to-day job and it may take some time till
|
| |
+ someone actually reviews your pull-request. Sending a "ping"/"bump" is
|
| |
totally fine, but only after a week or so (in other words, not
|
| |
- immediately after the pull-request has been opened).
|
| |
+ immediately after the pull-request has been created).
|
| |
|
| |
Once your code is reviewed, a few different things may happen:
|
| |
|
| |
@@ -149,12 +162,12 @@
|
| |
- Squash the changes to the original patches;
|
| |
|
| |
- Rebase your work on top of SSSD's git master:
|
| |
- ``git rebase github/master``;
|
| |
+ ``$ git rebase github/master``
|
| |
|
| |
- Please, do *not* merge the branches!
|
| |
|
| |
- Update the pull-request with the new patchset:
|
| |
- ``git push -f origin wip/meaningful_name``
|
| |
+ ``$ git push -f origin wip/meaningful_name``
|
| |
|
| |
- Leave a message in GitHub mentioning that your patchset has been
|
| |
updated.
|
| |
@@ -166,6 +179,91 @@
|
| |
add another core developer to the discussion. Usually democracy
|
| |
wins! :-)
|
| |
|
| |
+ Notes for Maintainers
|
| |
+ ~~~~~~~~~~~~~~~~~~~~~
|
| |
+
|
| |
+ Reviewing pull requests
|
| |
+ ^^^^^^^^^^^^^^^^^^^^^^^
|
| |
+
|
| |
+ The list of open pull requests can be found at
|
| |
+ `https://github.com/SSSD/sssd/pulls <https://github.com/SSSD/sssd/pulls>`__.
|
| |
+
|
| |
+ Any GitHub user can comment on the code:
|
| |
+
|
| |
+ - either add a comment to the text field, or
|
| |
+
|
| |
+ - click on the individual commit links and add comments inline to the diff.
|
| |
+
|
| |
+ Only collaborators can self-assign a pull requests and add labels. If you
|
| |
+ would like to be added as a collaborator, please send an e-mail to `sssd-devel
|
| |
+ <https://docs.pagure.org/SSSD.sssd/developers/contribute.html#contribute>`__
|
| |
+ and ask to be added.
|
| |
+
|
| |
+ If you want to formally review a pull request, please assign the pull request
|
| |
+ to yourself. This indicates that you'll be working with the submitter on
|
| |
+ pushing their pull requests upstream. You don't need to assign the pull
|
| |
+ request if you just want to add a one-time comment. The pull-request
|
| |
+ assignee(s) will be added as ``Reviewed-By`` tags when pushing to the Pagure
|
| |
+ repository.
|
| |
+
|
| |
+ If there is an issue in the code that you feel warrants a patch respin, add
|
| |
+ the ``changes requested`` label to the pull request.
|
| |
+
|
| |
+ Once you agree with the pull request, add the ``accepted`` label to the pull
|
| |
+ request. One of the gatekeepers will then push the pull request to the
|
| |
+ sssd repository manually.
|
| |
+
|
| |
+ If a pull-request is submitted by someone from outside the core team,
|
| |
+ the CI tests won't run to make sure some potentially malicious code
|
| |
+ is not ran on the CI nodes. To allow the code to be tested, one of
|
| |
+ the core developers must add: ::
|
| |
+
|
| |
+ ok to test
|
| |
+
|
| |
+ as a comment to the pull request. An example of one such pull request
|
| |
+ can be found `here <https://github.com/SSSD/sssd/pull/35>`__.
|
| |
+
|
| |
+ **Pro-tips:**
|
| |
+
|
| |
+ - Pressing ``l`` on the request allows to set labels without reaching
|
| |
+ for the mouse. You can also set assignee by pressing ``a``.
|
| |
+
|
| |
+ - You can add pull requests as refs and check them out as branches locally.
|
| |
+ To do that, add another ``fetch`` directive to your GitHub remote definition
|
| |
+ using ``$ git config``. ::
|
| |
+
|
| |
+ GITHUB_REMOTE="github"
|
| |
+ git config --add remote.${GITHUB_REMOTE}.fetch "+refs/pull/*/head:refs/remotes/${GITHUB_REMOTE}/pull/*"
|
| |
+
|
| |
+ Then you can fetch and checkout the pull requests with: ::
|
| |
+
|
| |
+ git fetch github
|
| |
+ git checkout -b pr7review --track github/pull/7
|
| |
+
|
| |
+ Pushing a pull request
|
| |
+ ^^^^^^^^^^^^^^^^^^^^^^
|
| |
+
|
| |
+ Only pull requests with an ``ack`` label can be pushed.
|
| |
+
|
| |
+ To push a patch, first apply it, for example: ::
|
| |
+
|
| |
+ hub am https://github.com/SSSD/sssd/pull/5
|
| |
+
|
| |
+ Don't forget to add the ``Reviewed-By`` tags, based on the pull request
|
| |
+ assignee. It's recommended to use the pre-push hook from ``contrib/git/pre-push``
|
| |
+ that rejects any pushes without a ``Reviewed-By`` tag.
|
| |
+
|
| |
+ Then check again what patches would be pushed: ::
|
| |
+
|
| |
+ git push -n github master
|
| |
+
|
| |
+ And if the hashes look OK, finally push the patches: ::
|
| |
+
|
| |
+ git push github master
|
| |
+
|
| |
+ Finally, add the commit hashes to the pull request page, add the label
|
| |
+ ``pushed`` and close the pull request.
|
| |
+
|
| |
Notes
|
| |
-----
|
| |
|
| |
@@ -175,4 +273,4 @@
|
| |
|
| |
In case you spot something wrong in this page, please, open an issue
|
| |
and/or a pull-request to our `sssd-docs
|
| |
- repo <https://pagure.io/SSSD/docs>`__
|
| |
+ repo <https://pagure.io/SSSD/docs>`__.
|
| |
sobek
commented 6 years ago
Resolves:
https://pagure.io/SSSD/sssd/issue/3557