From 0e75eda943126aca089e6e96fd02137dadc843de Mon Sep 17 00:00:00 2001 From: Fabiano Fidêncio Date: Jul 28 2017 12:34:44 +0000 Subject: Add a "Getting Started" page This page has the object to help: - newcomers to get around with the project and the with the github workflow; - developers to save some time, as they don't have to explain those very same things over and over again; Signed-off-by: Fabiano Fidêncio --- diff --git a/index.rst b/index.rst index 1baa991..9c661e2 100644 --- a/index.rst +++ b/index.rst @@ -23,6 +23,7 @@ Contents: .. toctree:: :maxdepth: 2 + newcomers/index.rst users/index.rst developers/index.rst diff --git a/newcomers/getting_started.rst b/newcomers/getting_started.rst new file mode 100644 index 0000000..651bd6d --- /dev/null +++ b/newcomers/getting_started.rst @@ -0,0 +1,178 @@ +.. highlight:: none + +Getting started with SSSD +========================= + +This document will describe the step-by-step to "How to make your first +contribution to SSSD project". + +Setting up an environment for development +----------------------------------------- + +There are several ways to do so, but the one recommended by the author +of this document is by simply using the +`pki-vagans `__ project created by +Christian Heimes. + +In the `pki-vagans `__ you'll be +able to find all the instruction that you need to know, but let's make +a really brief summary here. + +- Clone the repo: ``$ git clone https://github.com/tiran/pki-vagans`` + +- Switch to the IPA directory: ``$ cd pki-vagans/ipa`` + +- Run: ``$ sudo ./setup.sh`` + +Sometimes the initial provision fails. In case it happens, please do, +from the very same directory: + +- ``$ sudo vagrant up --no-provision`` + +- ``$ sudo vagrant provision`` + +Once the machines are up, you can connect to the client machine by +doing: + +- ``$ vagrant ssh ipaclient1`` + +On the client machine you can get a Kerberos ticket for the admin user, +who's password is 'Secret123': + +- ``$ kinit admin`` + +There's a known issue about the machine, sometimes, not being able to +update its packages. In case you hit this issue, please, do, from the +very same IPA folder in your host machine: + +- ``$ vagrant ssh ipamaster`` + +- ``$ sudo vim /etc/named.conf`` + +- Set the dnssec-enable and dnssec-validation to, as shown below: :: + + dnssec-enable no; + dnssec-validation no; + +- Restart the named-pkcs11.service: + ``sudo systemctl restart named-pkcs11.service`` + +GitHub workflow +--------------- + +SSSD is hosted on `pagure.io `_ but the +development happens on `GitHub `__. + +So, the first thing to contribute to SSSD is forking our `GitHub +`__ repository. + +In order to do so, go to our `SSSD's github page +`__, 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 ... + +- Clone your own SSSD's fork: + ``$ git clone git@github.com:/sssd.git`` + +- Add `SSSD's github repo `__ as a + remote repo: ``$ git remote add github https://github.com/SSSD/sssd`` + +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! + +- Create your local branch: ``git checkout -b wip/meaningful_name`` + +Considering you have built SSSD following the instructions provided +in our `Contribute page +`__ , +have made your changes following our `Coding guidelines +`__ and +have commited your changes following our `git-commit-template +`__ and +have implemented some unit/integration tests to ensure we're never hit +this very same issue again in the future ... now is time to open your +pull-request. + +The way the author of this documment does is: + +- Push the changes to *your* SSSD's repo: + ``$ git push origin wip/meaningful_name`` + +- Go to yours GitHub page; + +- Open the Pull Request by using GitHub's web UI. + +Here, I'd like to add some really basic etiquette rules for opening the +pull-request: + +- The description of your pull-request *must* be meaningful; + +- The message of your pull-request *must* briefly describe the reason + behind this pull-request; + +- The message of your pull-request *should* contain the steps to + 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 +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 +totally fine, but only after a week or so (in other words, not +immediately after the pull-request has been opened). + +Once your code is reviewed, a few different things may happen: + +- Your patch is "Accepted": it means the patch is good enough to be + merged to SSSD's repo without any changes. + +- Changes are requested: it means that something has to be changed in + your patch before it gets merged to SSSD; s repo. In this case, + you'd like to: + + - Carefully read and understand the changes required by the reviewer; + + - In case you did *not* understand the required changes, comment in + the pull-request asking your doubts till you have everything + crystal clear in your mind. Don't be afraid to do that, the core + developers are around to help! :-) + + - Please, do *not* privately ping the developers for all your + doubts. Discussing in the pull-request is a better and more + transparent way to do so *and* also doesn't interrupt the + developr from any other task they are doing. + + - Make the changes in your patches; + + - Squash the changes to the original patches; + + - Rebase your work on top of SSSD's git 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`` + + - Leave a message in GitHub mentioning that your patchset has been + updated. + +- Your patch is rejected: it means that your patch was rejected and the + reason for this will be explained in the pull-request. + + - In case you do *not* agree with the reviewer, please, feel free to + add another core developer to the discussion. Usually democracy + wins! :-) + +Notes +----- + +As mentioned in the beginning, there are several different ways to +contribute and you may need to find the one that fits better for +yourself. + +In case you spot something wrong in this page, please, open an issue +and/or a pull-request to our `sssd-docs +repo `__ diff --git a/newcomers/index.rst b/newcomers/index.rst new file mode 100644 index 0000000..743d56b --- /dev/null +++ b/newcomers/index.rst @@ -0,0 +1,11 @@ +Newcomers Guide +=============== + +This guide describes the best practices for newcomers who are willing to +contribute to the SSSD project. +and troubleshoot SSSD. + +.. toctree:: + :maxdepth: 1 + + getting_started