From 3d9dca9e260cbd5181fddeb51cf0aa048ef21e32 Mon Sep 17 00:00:00 2001 From: René Genz Date: Dec 15 2017 09:36:19 +0000 Subject: 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..8131c94 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..caf3587 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 ``accepted`` 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 `__.