From b734302fdb56b282b1f74536b66f01c8beb3bed1 Mon Sep 17 00:00:00 2001 From: René Genz Date: Nov 01 2017 21:42:26 +0000 Subject: [PATCH 1/2] Fix spelling mistakes --- diff --git a/README.md b/README.md index d8b7701..e7e3908 100644 --- a/README.md +++ b/README.md @@ -4,27 +4,27 @@ This repository contains the sources of the documentation of SSSD. You can contribute to SSSD by improving the documentation! If you are looking for the rendered documentation in HTML format, please see -the [docs link on the sssd pagure instance](https://pagure.io/docs/SSSD/sssd/). +the [docs link on SSSD's Pagure instance](https://pagure.io/docs/SSSD/sssd/). ## Contributing to the SSSD documentation The SSSD documentation is written in RST. To contribute to the documentation: 1. Make sure Sphinx is installed (`dnf install python-sphinx graphviz` on Fedora) -2. Fork [this repository](https://pagure.io/SSSD/docs) on pagure -3. Add your content. The [sphinx documentation](http://www.sphinx-doc.org/en/stable/contents.html) +2. Fork [this repository](https://pagure.io/SSSD/docs) on Pagure +3. Add your content. The [Sphinx documentation](http://www.sphinx-doc.org/en/stable/contents.html) might prove useful. If you are adding a new page, don't forget to add it to an index! 4. Build the HTML pages with `make html` 5. Inspect that the result looks good. The HTML result is located in the `_build` directory 6. Create a local commit with your changes -7. Push it to your pagure fork +7. Push it to your Pagure fork 8. Create a pull request One of the SSSD maintainers will then review the pull request. For fixing trivial issues like typos, you can also use the "Fork and edit" -button in the [sssd docs repository](https://pagure.io/SSSD/docs) or just the +button in the [SSSD docs repository](https://pagure.io/SSSD/docs) or just the "Edit" button in your fork. ## Building the SSSD documentation diff --git a/design_pages/auto_private_groups.rst b/design_pages/auto_private_groups.rst index 790ad82..a7b5496 100644 --- a/design_pages/auto_private_groups.rst +++ b/design_pages/auto_private_groups.rst @@ -31,7 +31,7 @@ Overview of the solution ------------------------ Most of the low-level functionality in the sysdb layer had been developed for many years for use in the ``local`` provider. At the same time, there -are also most of the infrastrucure ready in the LDAP provider and the +are also most of the infrastructure ready in the LDAP provider and the NSS responder, because the automatic private groups are used by default already for trusted domains with ID mapping enabled. @@ -56,7 +56,7 @@ Instead of resurrecting the old option, we should introduce a newly named option that would be understood by admins better, such as ``auto_private_groups``. The new option must be read on SSSD startup and set the ``sss_domain_info->mpg`` flag, which is currently auto-enabled with -sudomains only. +subdomains only. The code branch that saves the user (currently ``sdap_save_user``) must be extended to allow setting the GID number to be the same as UID number for @@ -84,16 +84,16 @@ The ``auto_private_groups`` option will default to ``false``. How To Test ----------- The primary use-cases are SSSD being a client of a generic LDAP server -and SSSD on a Linux machine directly joined to an AD domain with +and SSSD on a GNU/Linux machine directly joined to an AD domain with ``id_provider=ad``. In both cases, setting the ``auto_private_groups`` option to ``true`` should result in the ``initgroups`` call returning the primary GID number of the user with the same value and resolving to the same name as the -primary UID namber and the username. +primary UID number and the username. -Other intefaces should produce symmetrical results, although at least in -the case of the D-Bus based IFP interface, is it currently not the case, +Other interfaces should produce symmetrical results, although at least in +the case of the D-Bus based IFP interface, it is currently not the case, see `ticket #3543 `_. For example, here is an output of a test user with private groups autogenerated:: diff --git a/index.rst b/index.rst index 49df875..d90dddb 100644 --- a/index.rst +++ b/index.rst @@ -17,8 +17,8 @@ The primary resources to learn about SSSD or to get involved in its development * `Bug tracker `_ * `Mailing list for SSSD users discussion `_ * `Mailing list for SSSD development discussion `_ - * `Github mirror `_ - * `Github pull requests `_ + * `GitHub mirror `_ + * `GitHub pull requests `_ Contents: diff --git a/newcomers/index.rst b/newcomers/index.rst index 743d56b..b32d93c 100644 --- a/newcomers/index.rst +++ b/newcomers/index.rst @@ -2,8 +2,7 @@ Newcomers Guide =============== This guide describes the best practices for newcomers who are willing to -contribute to the SSSD project. -and troubleshoot SSSD. +contribute to the SSSD project, and troubleshoot SSSD. .. toctree:: :maxdepth: 1 diff --git a/users/reporting_bugs.rst b/users/reporting_bugs.rst index cc1efbe..c914438 100644 --- a/users/reporting_bugs.rst +++ b/users/reporting_bugs.rst @@ -14,7 +14,7 @@ Where to file the bugs? You'll need a `Fedora Account System `_ login to file a bug. When you have one, navigate to -`the new ticket form `_ +`the new ticket form `_. Some bugs will be automatically cloned from distribution bug-trackers, such as http://bugzilla.redhat.com. @@ -103,7 +103,7 @@ When the program crashes, save the core file and backtrace:: Then attach the core file and the backtrace. -When connecting to a sssd process with ``gdb``, you should increase the +When connecting to an sssd process with ``gdb``, you should increase the ``timeout`` option in the debugged process's section up from its default value, such as:: From f8c904879b5f7617f16318490d51cbdfc52ea9dd Mon Sep 17 00:00:00 2001 From: René Genz Date: Nov 01 2017 23:33:17 +0000 Subject: [PATCH 2/2] Merge old wiki info for GitHub workflow Resolves: https://pagure.io/SSSD/sssd/issue/3557 --- diff --git a/developers/contribute.rst b/developers/contribute.rst index 70194b0..3c7c2b7 100644 --- a/developers/contribute.rst +++ b/developers/contribute.rst @@ -6,7 +6,8 @@ Contribute There are many ways you can contribute to the System Security Services Daemon. This page should provide some basic pointers. -SSSD development discussions occur either on the `SSSD development list +SSSD development discussions occur either on the `SSSD development +(sssd-devel) mailing list `__ or on the `#sssd IRC channel `__ on `freenode `__. Keep in mind that SSSD developers @@ -39,25 +40,39 @@ Source Code Repository For the SSSD project, we use the `Git `__ -source control system. :: +source control system. + +Hosted on `Pagure `__ are the `documentation +`__, the `issue tracker +`__, and the referential repository: :: https://pagure.io/SSSD/sssd.git -We also maintain a read-only mirror on GitHub. :: +SSSD's repository on Pagure is mirrored to GitHub and maintained as read-only instance: :: https://github.com/SSSD/sssd +The preferred way for sending patches is to create pull requests either +on Pagure or GitHub. +You can also e-mail your patch as an attachment to the `sssd-devel +`__ +mailing list. +A guide for a `GitHub workflow +`__ +is available. The paragraphs below assume you are using Pagure. + Tasks for newcomers ------------------- We try to mark tickets that don't require too much existing knowledge -with the ``easyfix`` keyword in Trac. We also prepared `a Pagure query +with the ``easyfix`` keyword in our issue tracker. We also prepared `a query `__ that lists the easy fixes. Before starting the work on any of these tickets, it might be a good idea -to contact the SSSD developers on the `sssd-devel list -`__ -and check if the ticket is still valid or ask for guidance in general. +to contact the SSSD developers on the `sssd-devel +`__ +mailing list and check if the ticket is still valid or ask for guidance in +general. Getting the source ~~~~~~~~~~~~~~~~~~ @@ -106,7 +121,6 @@ You can also enable the commit template by: :: git config commit.template .git-commit-template - Building SSSD ------------- @@ -232,9 +246,39 @@ currently outdated and a `new updated C style guide `__ was written for SSSD. +Spell-checker +~~~~~~~~~~~~~ + +Please, check the spelling before submitting. + +Use your favorite spell-checker. Checking with LibreOffice can be done like: + +* open file(s) that contain(s) changes with "LibreOffice Writer" + +* set the document language to "English (USA)" + (either `Tools -- Language -- For all Text` + or select whole text with keyboard shortcut Ctrl+A, then click at + the bottom in the middle) + +* to start the check press F7 + (equals `Tools -- Spelling and Grammar ...`) + +* press [Ignore Once] for spelling mistakes + press [Ignore All] to ignore the known good string until LibreOffice is closed + press [Add to Dictionary] to add the word to the known good list + +* fix spelling mistake with editor, not LibreOffice + +* in terminal run `fgrep -ri ${BADWORD}` or `egrep -r 'REGEXP'` + to double-check and find other instances of problem + Submitting ~~~~~~~~~~ +Please, read the `basic etiquette` paragraph of the `GitHub workflow +`__ +before submitting. + Make your changes and then add any new or modified files to a change-set with the command: :: @@ -264,8 +308,7 @@ Ticket #2789 `__ where one patch makes the ``resolv_is_address()`` function public with tests and the other adds the function in the SSSD providers. -Once your changes are ready for submission, submit it via a `GitHub pull -request `__. +Once your changes are ready for submission, submit it via a pull request. If a patch isn't accepted on the first review, you will need to modify it and resubmit it. When this happens, you will want to amend your @@ -281,7 +324,7 @@ If you need to make changes to earlier patches in your tree, you can use :: and follow the directions in the interactive rebase to modify specific patches. -Then just re-push the patches to GitHub, the pull request will be +Then just re-push the patches, the pull request will be refreshed automatically. Patch metadata diff --git a/newcomers/getting_started.rst b/newcomers/getting_started.rst index db32ffe..c36e3a8 100644 --- a/newcomers/getting_started.rst +++ b/newcomers/getting_started.rst @@ -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 @@ very same IPA folder in your host machine: 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 `_ but the -development happens on `GitHub `__. +For general information about SSSD hosting see the paragraph +`Source Code Repository `__. +It covers using SSSD's Pagure repository. -So, the first thing to contribute to SSSD is forking our `GitHub -`__ repository. +This section assumes you use GitHub. -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 ... +At first some general information. All pull request activity generates +an e-mail notification to the `sssd-devel +`__ +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 `__, 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:/sssd.git`` -- Add `SSSD's github repo `__ 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 -`__ , +`__, have made your changes following our `Coding guidelines -`__ and +`__, have committed your changes following our `git-commit-template -`__ and +`__, 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 @@ The way the author of this document does is: - 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 `__ tool: + ``$ hub pull-request`` Here, I'd like to add some really basic etiquette rules for opening the pull-request: @@ -114,14 +126,15 @@ pull-request: 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 @@ Once your code is reviewed, a few different things may happen: - 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 @@ Once your code is reviewed, a few different things may happen: 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 `__. + +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 +`__ +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 `__. + +**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 @@ yourself. In case you spot something wrong in this page, please, open an issue and/or a pull-request to our `sssd-docs -repo `__ +repo `__. diff --git a/users/faq.rst b/users/faq.rst index 0bcb076..8533174 100644 --- a/users/faq.rst +++ b/users/faq.rst @@ -396,7 +396,7 @@ Tracking bugs and enhancement requests If you think you have found a bug or would like to file an enhancement request, create a `new issue -`__ in the SSSD's Pagure instance. -Logging into the Trac instance requires a Fedora Account System login. +`__. +Logging into the issue tracker requires a Fedora Account System login. To create one, use the `FAS interface `__.