#, fuzzy msgid "" msgstr "" "Project-Id-Version: Swift 2.37.0.dev96\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2025-12-09 16:39+0000\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: ../../../CONTRIBUTING.rst:2 msgid "Contributing to OpenStack Swift" msgstr "" #: ../../../CONTRIBUTING.rst:5 msgid "Who is a Contributor?" msgstr "" #: ../../../CONTRIBUTING.rst:7 msgid "" "Put simply, if you improve Swift, you're a contributor. The easiest way to " "improve the project is to tell us where there's a bug. In other words, " "filing a bug is a valuable and helpful way to contribute to the project." msgstr "" #: ../../../CONTRIBUTING.rst:11 msgid "" "Once a bug has been filed, someone will work on writing a patch to fix the " "bug. Perhaps you'd like to fix a bug. Writing code to fix a bug or add new " "functionality is tremendously important." msgstr "" #: ../../../CONTRIBUTING.rst:15 msgid "" "Once code has been written, it is submitted upstream for review. All code, " "even that written by the most senior members of the community, must pass " "code review and all tests before it can be included in the project. " "Reviewing proposed patches is a very helpful way to be a contributor." msgstr "" #: ../../../CONTRIBUTING.rst:20 msgid "" "Swift is nothing without the community behind it. We'd love to welcome you " "to our community. Come find us in #openstack-swift on OFTC IRC or on the " "OpenStack dev mailing list." msgstr "" #: ../../../CONTRIBUTING.rst:24 msgid "" "For general information on contributing to OpenStack, please check out the " "`contributor guide `_ to get " "started. It covers all the basics that are common to all OpenStack projects: " "the accounts you need, the basics of interacting with our Gerrit review " "system, how we communicate as a community, etc." msgstr "" #: ../../../CONTRIBUTING.rst:30 msgid "" "For more project information, feel free to check out the `Swift " "documentation `__." msgstr "" #: ../../../CONTRIBUTING.rst:33 msgid "Filing a Bug" msgstr "" #: ../../../CONTRIBUTING.rst:35 msgid "" "Filing a bug is the easiest way to contribute. You can find currently-" "tracked bugs on our `Launchpad. `__ Use " "the `Report a bug `__ link to " "file a new bug." msgstr "" #: ../../../CONTRIBUTING.rst:39 msgid "" "If you find something in Swift that doesn't match the documentation or " "doesn't meet your expectations with how it should work, please let us know. " "Of course, if you ever get an error (like a Traceback message in the logs), " "we definitely want to know about that. We'll do our best to diagnose any " "problem and patch it as soon as possible." msgstr "" #: ../../../CONTRIBUTING.rst:45 msgid "" "A bug report, at minimum, should describe what you were doing that caused " "the bug. \"Swift broke, pls fix\" is not helpful. Instead, something like " "\"When I restarted syslog, Swift started logging traceback messages\" is " "very helpful. The goal is that we can reproduce the bug and isolate the " "issue in order to apply a fix. If you don't have full details, that's ok. " "Anything you can provide is helpful." msgstr "" #: ../../../CONTRIBUTING.rst:52 msgid "" "You may have noticed that there are many tracked bugs, but not all of them " "have been confirmed. If you take a look at an old bug report and you can " "reproduce the issue described, please leave a comment on the bug about that. " "It lets us all know that the bug is very likely to be valid." msgstr "" #: ../../../CONTRIBUTING.rst:58 msgid "Reviewing Someone Else's Code" msgstr "" #: ../../../CONTRIBUTING.rst:60 msgid "" "All code reviews in OpenStack projects are done on our Gerrit instance at " "`review.opendev.org `__. Reviewing patches is one of the most effective ways you can " "contribute to the community." msgstr "" #: ../../../CONTRIBUTING.rst:64 msgid "" "We've written a set of `Review Guidelines `__ to help you give good reviews." msgstr "" #: ../../../CONTRIBUTING.rst:67 msgid "" "To find out what reviews are priortiy in the community, you can read " "`Priority Reviews `__ " "on our wiki." msgstr "" #: ../../../CONTRIBUTING.rst:70 msgid "What do I work on?" msgstr "" #: ../../../CONTRIBUTING.rst:72 msgid "" "If you're looking for a way to write and contribute code, but you're not " "sure what to work on, check out the `\"wishlist\" bugs `__ in the bug " "tracker. These are normally smaller items that someone took the time to " "write down but didn't have time to implement." msgstr "" #: ../../../CONTRIBUTING.rst:77 msgid "" "And please join #openstack-swift on OFTC IRC to tell us what you're working " "on." msgstr "" #: ../../../CONTRIBUTING.rst:80 msgid "Getting Started" msgstr "" #: ../../../CONTRIBUTING.rst:82 msgid "https://docs.openstack.org/swift/latest/first_contribution_swift.html" msgstr "" #: ../../../CONTRIBUTING.rst:84 msgid "" "Once those steps have been completed, changes to OpenStack should be " "submitted for review via the Gerrit tool, following our `Development " "Workflow. `__" msgstr "" #: ../../../CONTRIBUTING.rst:87 msgid "" "Gerrit is the review system used in the OpenStack projects. We're sorry, but " "we won't be able to respond to pull requests submitted through GitHub." msgstr "" #: ../../../CONTRIBUTING.rst:90 msgid "" "Bugs should be filed `on Launchpad `__, " "not in GitHub's issue tracker." msgstr "" #: ../../../CONTRIBUTING.rst:94 msgid "Swift Design Principles" msgstr "" #: ../../../CONTRIBUTING.rst:96 msgid "`The Zen of Python `__" msgstr "" #: ../../../CONTRIBUTING.rst:97 msgid "Simple Scales" msgstr "" #: ../../../CONTRIBUTING.rst:98 msgid "Minimal dependencies" msgstr "" #: ../../../CONTRIBUTING.rst:99 msgid "Re-use existing tools and libraries when reasonable" msgstr "" #: ../../../CONTRIBUTING.rst:100 msgid "Leverage the economies of scale" msgstr "" #: ../../../CONTRIBUTING.rst:101 msgid "Small, loosely coupled RESTful services" msgstr "" #: ../../../CONTRIBUTING.rst:102 msgid "No single points of failure" msgstr "" #: ../../../CONTRIBUTING.rst:103 msgid "Start with the use case" msgstr "" #: ../../../CONTRIBUTING.rst:104 msgid "... then design from the cluster operator up" msgstr "" #: ../../../CONTRIBUTING.rst:105 msgid "If you haven't argued about it, you don't have the right answer yet :)" msgstr "" #: ../../../CONTRIBUTING.rst:107 msgid "If it is your first implementation, you probably aren't done yet :)" msgstr "" #: ../../../CONTRIBUTING.rst:109 msgid "" "Please don't feel offended by difference of opinion. Be prepared to advocate " "for your change and iterate on it based on feedback. Reach out to other " "people working on the project on `IRC `__ or the `mailing list `__ - we " "want to help." msgstr "" #: ../../../CONTRIBUTING.rst:118 msgid "Recommended workflow" msgstr "" #: ../../../CONTRIBUTING.rst:120 msgid "" "Set up a `Swift All-In-One VM `__\\ (SAIO)." msgstr "" #: ../../../CONTRIBUTING.rst:123 msgid "" "Make your changes. Docs and tests for your patch must land before or with " "your patch." msgstr "" #: ../../../CONTRIBUTING.rst:126 msgid "" "Run unit tests, functional tests, probe tests ``./.unittests`` ``./." "functests`` ``./.probetests``" msgstr "" #: ../../../CONTRIBUTING.rst:129 msgid "Run ``tox`` (no command-line args needed)" msgstr "" #: ../../../CONTRIBUTING.rst:131 msgid "``git review``" msgstr "" #: ../../../CONTRIBUTING.rst:134 msgid "Notes on Testing" msgstr "" #: ../../../CONTRIBUTING.rst:136 msgid "" "Running the tests above against Swift in your development environment (ie " "your SAIO) will catch most issues. Any patch you propose is expected to be " "both tested and documented and all tests should pass." msgstr "" #: ../../../CONTRIBUTING.rst:140 msgid "" "If you want to run just a subset of the tests while you are developing, you " "can use pytest:" msgstr "" #: ../../../CONTRIBUTING.rst:147 msgid "" "To check which parts of your code are being exercised by a test, you can run " "tox and then point your browser to swift/cover/index.html:" msgstr "" #: ../../../CONTRIBUTING.rst:154 msgid "" "Swift's unit tests are designed to test small parts of the code in isolation." " The functional tests validate that the entire system is working from an " "external perspective (they are \"black-box\" tests). You can even run " "functional tests against public Swift endpoints. The probetests are designed " "to test much of Swift's internal processes. For example, a test may write " "data, intentionally corrupt it, and then ensure that the correct processes " "detect and repair it." msgstr "" #: ../../../CONTRIBUTING.rst:162 msgid "" "When your patch is submitted for code review, it will automatically be " "tested on the OpenStack CI infrastructure. In addition to many of the tests " "above, it will also be tested by several other OpenStack test jobs." msgstr "" #: ../../../CONTRIBUTING.rst:167 msgid "" "Once your patch has been reviewed and approved by core reviewers and has " "passed all automated tests, it will be merged into the Swift source tree." msgstr "" #: ../../../CONTRIBUTING.rst:172 msgid "Ideas" msgstr "" #: ../../../CONTRIBUTING.rst:174 msgid "https://wiki.openstack.org/wiki/Swift/ideas" msgstr "" #: ../../../CONTRIBUTING.rst:176 msgid "" "If you're working on something, it's a very good idea to write down what " "you're thinking about. This lets others get up to speed, helps you " "collaborate, and serves as a great record for future reference. Write down " "your thoughts somewhere and put a link to it here. It doesn't matter what " "form your thoughts are in; use whatever is best for you. Your document " "should include why your idea is needed and your thoughts on particular " "design choices and tradeoffs. Please include some contact information " "(ideally, your IRC nick) so that people can collaborate with you." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:2 msgid "Review Guidelines" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:4 msgid "" "Effective code review is a skill like any other professional skill you " "develop with experience. Effective code review requires trust. No one is " "perfect. Everyone makes mistakes. Trust builds over time." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:8 msgid "" "This document will enumerate behaviors commonly observed and associated with " "competent reviews of changes purposed to the Swift code base. No one is " "expected to \"follow these steps\". Guidelines are not *rules*, not all " "behaviors will be relevant in all situations." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:13 msgid "Code review is collaboration, not judgement." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:15 msgid "Alistair Coles" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:18 msgid "Checkout the Change" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:20 msgid "" "You will need to have a copy of the change in an environment where you can " "freely edit and experiment with the code in order to provide a non-" "superficial review. Superficial reviews are not terribly helpful. Always try " "to be helpful. ;)" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:25 msgid "Check out the change so that you may begin." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:27 msgid "Commonly, ``git review -d ``" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:30 msgid "Run it" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:32 msgid "" "Imagine that you submit a patch to Swift, and a reviewer starts to take a " "look at it. Your commit message on the patch claims that it fixes a bug or " "adds a feature, but as soon as the reviewer downloads it locally and tries " "to test it, a severe and obvious error shows up. Something like a syntax " "error or a missing dependency." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:38 msgid "\"Did you even run this?\" is the review comment all contributors dread." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:40 msgid "" "Reviewers in particular need to be fearful merging changes that just don't " "work - or at least fail in frequently common enough scenarios to be " "considered \"horribly broken\". A comment in our review that says roughly " "\"I ran this on my machine and observed ``description of behavior change is " "supposed to achieve``\" is the most powerful defense we have against the " "terrible scorn from our fellow Swift developers and operators when we " "accidentally merge bad code." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:48 msgid "" "If you're doing a fair amount of reviews - you will participate in merging a " "change that will break my clusters - it's cool - I'll do it to you at some " "point too (sorry about that). But when either of us go look at the reviews " "to understand the process gap that allowed this to happen - it better not be " "just because we were too lazy to check it out and run it before it got " "merged." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:55 msgid "Or be warned, you may receive, the dreaded..." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:57 msgid "\"Did you even *run* this?\"" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:59 msgid "I'm sorry, I know it's rough. ;)" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:62 msgid "Consider edge cases very seriously" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:64 msgid "" "Saying \"that should rarely happen\" is the same as saying \"that *will* " "happen\"" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:67 msgid "Douglas Crockford" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:69 msgid "" "Scale is an *amazingly* abusive partner. If you contribute changes to Swift " "your code is running - in production - at scale - and your bugs cannot hide. " "I wish on all of us that our bugs may be exceptionally rare - meaning they " "only happen in extremely unlikely edge cases. For example, bad things that " "happen only 1 out of every 10K times an op is performed will be discovered " "in minutes. Bad things that happen only 1 out of every one billion times " "something happens will be observed - by multiple deployments - over the " "course of a release. Bad things that happen 1/100 times some op is performed " "are considered \"horribly broken\". Tests must exhaustively exercise " "possible scenarios. Every system call and network connection will raise an " "error and timeout - where will that Exception be caught?" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:83 msgid "Run the tests" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:85 msgid "" "Yes, I know Gerrit does this already. You can do it *too*. You might not " "need to re-run *all* the tests on your machine - it depends on the change. " "But, if you're not sure which will be most useful - running all of them best " "- unit - functional - probe. If you can't reliably get all tests passing in " "your development environment you will not be able to do effective reviews. " "Whatever tests/suites you are able to exercise/validate on your machine " "against your config you should mention in your review comments so that other " "reviewers might choose to do *other* testing locally when they have the " "change checked out." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:95 ../../../REVIEW_GUIDELINES.rst:247 msgid "e.g." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:97 msgid "" "I went ahead and ran probe/test_object_metadata_replication.py on my machine " "with both sync_method = rsync and sync_method = ssync - that works for me - " "but I didn't try it with object_post_as_copy = false" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:103 msgid "Maintainable Code is Obvious" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:105 msgid "" "Style is an important component to review. The goal is maintainability." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:107 msgid "" "However, keep in mind that generally style, readability and maintainability " "are orthogonal to the suitability of a change for merge. A critical bug fix " "may be a well written pythonic masterpiece of style - or it may be a hack-y " "ugly mess that will absolutely need to be cleaned up at some point - but it " "absolutely should merge because: CRITICAL. BUG. FIX." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:114 msgid "" "You should comment inline to praise code that is \"obvious\". You should " "comment inline to highlight code that you found to be \"obfuscated\"." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:117 msgid "" "Unfortunately \"readability\" is often subjective. We should remember that " "it's probably just our own personal preference. Rather than a comment that " "says \"You should use a list comprehension here\" - rewrite the code as a " "list comprehension, run the specific tests that hit the relevant section to " "validate your code is correct, then leave a comment that says:" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:124 msgid "I find this more readable:" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:126 msgid "``diff with working tested code``" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:128 msgid "" "If the author (or another reviewer) agrees - it's possible the change will " "get updated to include that improvement before it is merged; or it may " "happen in a follow-up change." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:132 msgid "" "However, remember that style is non-material - it is useful to provide (via " "diff) suggestions to improve maintainability as part of your review - but if " "the suggestion is functionally equivalent - it is by definition optional." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:137 msgid "Commit Messages" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:139 msgid "Read the commit message thoroughly before you begin the review." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:141 msgid "" "Commit messages must answer the \"why\" and the \"what for\" - more so than " "the \"how\" or \"what it does\". Commonly this will take the form of a short " "description:" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:145 msgid "What is broken - without this change" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:146 msgid "What is impossible to do with Swift - without this change" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:147 msgid "What is slower/worse/harder - without this change" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:149 msgid "" "If you're not able to discern why a change is being made or how it would be " "used - you may have to ask for more details before you can successfully " "review it." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:153 msgid "" "Commit messages need to have a high consistent quality. While many things " "under source control can be fixed and improved in a follow-up change - " "commit messages are forever. Luckily it's easy to fix minor mistakes using " "the in-line edit feature in Gerrit! If you can avoid ever having to *ask* " "someone to change a commit message you will find yourself an amazingly " "happier and more productive reviewer." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:160 msgid "" "Also commit messages should follow the OpenStack Commit Message guidelines, " "including references to relevant impact tags or bug numbers. You should hand " "out links to the OpenStack Commit Message guidelines *liberally* via " "comments when fixing commit messages during review." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:166 msgid "" "Here you go: `GitCommitMessages `_" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:169 msgid "New Tests" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:171 msgid "" "New tests should be added for all code changes. Historically you should " "expect good changes to have a diff line count ratio of at least 2:1 tests to " "code. Even if a change has to \"fix\" a lot of *existing* tests, if a change " "does not include any *new* tests it probably should not merge." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:177 msgid "" "If a change includes a good ratio of test changes and adds new tests - you " "should say so in your review comments." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:180 msgid "If it does not - you should write some!" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:182 msgid "" "... and offer them to the patch author as a diff indicating to them that " "\"something\" like these tests I'm providing as an example will *need* to be " "included in this change before it is suitable to merge. Bonus points if you " "include suggestions for the author as to how they might improve or expand " "upon the tests stubs you provide." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:188 msgid "" "Be *very* careful about asking an author to add a test for a \"small " "change\" before attempting to do so yourself. It's quite possible there is a " "lack of existing test infrastructure needed to develop a concise and clear " "test - the author of a small change may not be the best person to introduce " "a large amount of new test infrastructure. Also, most of the time remember " "it's *harder* to write the test than the change - if the author is unable to " "develop a test for their change on their own you may prevent a useful change " "from being merged. At a minimum you should suggest a specific unit test that " "you think they should be able to copy and modify to exercise the behavior in " "their change. If you're not sure if such a test exists - replace their " "change with an Exception and run tests until you find one that blows up." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:201 msgid "Documentation" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:203 msgid "" "Most changes should include documentation. New functions and code should " "have Docstrings. Tests should obviate new or changed behaviors with " "descriptive and meaningful phrases. New features should include changes to " "the documentation tree. New config options should be documented in example " "configs. The commit message should document the change for the change log." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:210 msgid "" "Always point out typos or grammar mistakes when you see them in review, but " "also consider that if you were able to recognize the intent of the statement " "- documentation with typos may be easier to iterate and improve on than " "nothing." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:215 msgid "" "If a change does not have adequate documentation it may not be suitable to " "merge. If a change includes incorrect or misleading documentation or is " "contrary to *existing* documentation is probably is not suitable to merge." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:219 msgid "Every change could have better documentation." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:221 msgid "" "Like with tests, a patch isn't done until it has docs. Any patch that adds a " "new feature, changes behavior, updates configs, or in any other way is " "different than previous behavior requires docs. manpages, sample configs, " "docstrings, descriptive prose in the source tree, etc." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:227 msgid "Reviewers Write Code" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:229 msgid "" "Reviews have been shown to provide many benefits - one of which is shared " "ownership. After providing a positive review you should understand how the " "change works. Doing this will probably require you to \"play with\" the " "change." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:233 msgid "" "You might functionally test the change in various scenarios. You may need to " "write a new unit test to validate the change will degrade gracefully under " "failure. You might have to write a script to exercise the change under some " "superficial load. You might have to break the change and validate the new " "tests fail and provide useful errors. You might have to step through some " "critical section of the code in a debugger to understand when all the " "possible branches are exercised in tests." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:241 msgid "" "When you're done with your review an artifact of your effort will be " "observable in the piles of code and scripts and diffs you wrote while " "reviewing. You should make sure to capture those artifacts in a paste or " "gist and include them in your review comments so that others may reference " "them." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:249 msgid "When I broke the change like this:" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:251 msgid "``diff``" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:253 msgid "it blew up like this:" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:255 msgid "``unit test failure``" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:258 msgid "" "It's not uncommon that a review takes more time than writing a change - " "hopefully the author also spent as much time as you did *validating* their " "change but that's not really in your control. When you provide a positive " "review you should be sure you understand the change - even seemingly trivial " "changes will take time to consider the ramifications." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:265 msgid "Leave Comments" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:267 msgid "Leave. Lots. Of. Comments." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:269 msgid "" "A popular web comic has stated that `WTFs/Minute `_ is the *only* valid measurement of code quality." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:273 msgid "" "If something initially strikes you as questionable - you should jot down a " "note so you can loop back around to it." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:276 msgid "" "However, because of the distributed nature of authors and reviewers it's " "*imperative* that you try your best to answer your own questions as part of " "your review." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:280 msgid "" "Do not say \"Does this blow up if it gets called when xyz\" - rather try and " "find a test that specifically covers that condition and mention it in the " "comment so others can find it more quickly. Or if you can find no such test, " "add one to demonstrate the failure, and include a diff in a comment. " "Hopefully you can say \"I *thought* this would blow up, so I wrote this " "test, but it seems fine.\"" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:287 msgid "" "But if your initial reaction is \"I don't understand this\" or \"How does " "this even work?\" you should notate it and explain whatever you *were* able " "to figure out in order to help subsequent reviewers more quickly identify " "and grok the subtle or complex issues." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:292 msgid "" "Because you will be leaving lots of comments - many of which are potentially " "not highlighting anything specific - it is VERY important to leave a good " "summary. Your summary should include details of how you reviewed the change. " "You may include what you liked most, or least." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:298 msgid "" "If you are leaving a negative score ideally you should provide clear " "instructions on how the change could be modified such that it would be " "suitable for merge - again diffs work best." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:303 msgid "Scoring" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:305 msgid "Scoring is subjective. Try to realize you're making a judgment call." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:307 msgid "" "A positive score means you believe Swift would be undeniably better off with " "this code merged than it would be going one more second without this change " "running in production immediately. It is indeed high praise - you should be " "sure." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:312 msgid "" "A negative score means that to the best of your abilities you have not been " "able to your satisfaction, to justify the value of a change against the cost " "of its deficiencies and risks. It is a surprisingly difficult chore to be " "confident about the value of unproven code or a not well understood use-case " "in an uncertain world, and unfortunately all too easy with a **thorough** " "review to uncover our defects, and be reminded of the risk of... regression." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:320 msgid "" "Reviewers must try *very* hard first and foremost to keep master stable." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:322 msgid "" "If you can demonstrate a change has an incorrect *behavior* it's almost " "without exception that the change must be revised to fix the defect *before* " "merging rather than letting it in and having to also file a bug." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:327 msgid "Every commit must be deployable to production." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:329 msgid "" "Beyond that - almost any change might be merge-able depending on its merits! " " Here are some tips you might be able to use to find more changes that " "should merge!" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:333 msgid "" "Fixing bugs is HUGELY valuable - the *only* thing which has a higher cost " "than the value of fixing a bug - is adding a new bug - if it's broken and " "this change makes it fixed (without breaking anything else) you have a " "winner!" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:338 msgid "" "Features are INCREDIBLY difficult to justify their value against the cost of " "increased complexity, lowered maintainability, risk of regression, or new " "defects. Try to focus on what is *impossible* without the feature - when you " "make the impossible possible, things are better. Make things better." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:344 msgid "" "Purely test/doc changes, complex refactoring, or mechanical cleanups are " "quite nuanced because there's less concrete objective value. I've seen lots " "of these kind of changes get lost to the backlog. I've also seen some " "success where multiple authors have collaborated to \"push-over\" a change " "rather than provide a \"review\" ultimately resulting in a quorum of three " "or more \"authors\" who all agree there is a lot of value in the change - " "however subjective." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:353 msgid "Because the bar is high - most reviews will end with a negative score." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:355 msgid "" "However, for non-material grievances (nits) - you should feel confident in a " "positive review if the change is otherwise complete correct and undeniably " "makes Swift better (not perfect, *better*). If you see something worth " "fixing you should point it out in review comments, but when applying a score " "consider if it *need* be fixed before the change is suitable to merge vs. " "fixing it in a follow up change? Consider if the change makes Swift so " "undeniably *better* and it was deployed in production without making any " "additional changes would it still be correct and complete? Would releasing " "the change to production without any additional follow up make it more " "difficult to maintain and continue to improve Swift?" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:367 msgid "" "Endeavor to leave a positive or negative score on every change you review." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:369 msgid "Use your best judgment." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:372 msgid "A note on Swift Core Maintainers" msgstr "" #: ../../../REVIEW_GUIDELINES.rst:374 msgid "" "Swift Core maintainers may provide positive reviews scores that *look* " "different from your reviews - a \"+2\" instead of a \"+1\"." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:377 msgid "But it's *exactly the same* as your \"+1\"." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:379 msgid "" "It means the change has been thoroughly and positively reviewed. The only " "reason it's different is to help identify changes which have received " "multiple competent and positive reviews. If you consistently provide " "competent reviews you run a *VERY* high risk of being approached to have " "your future positive review scores changed from a \"+1\" to \"+2\" in order " "to make it easier to identify changes which need to get merged." msgstr "" #: ../../../REVIEW_GUIDELINES.rst:387 msgid "" "Ideally a review from a core maintainer should provide a clear path forward " "for the patch author. If you don't know how to proceed respond to the " "reviewers comments on the change and ask for help. We'd love to try and help." "" msgstr "" #: ../../source/contributor/contributing.rst:4 msgid "Community" msgstr "" #: ../../source/contributor/contributing.rst:7 msgid "Communication" msgstr "" #: ../../source/contributor/contributing.rst:8 msgid "IRC" msgstr "" #: ../../source/contributor/contributing.rst:9 msgid "" "People working on the Swift project may be found in the ``#openstack-swift`` " "channel on OFTC during working hours in their timezone. The channel is " "logged, so if you ask a question when no one is around, you can `check the " "log `__ to see " "if it's been answered." msgstr "" #: ../../source/contributor/contributing.rst:16 msgid "weekly meeting" msgstr "" #: ../../source/contributor/contributing.rst:17 msgid "" "This is a Swift team meeting. The discussion in this meeting is about all " "things related to the Swift project:" msgstr "" #: ../../source/contributor/contributing.rst:20 msgid "time: http://eavesdrop.openstack.org/#Swift_Team_Meeting" msgstr "" #: ../../source/contributor/contributing.rst:21 msgid "agenda: https://wiki.openstack.org/wiki/Meetings/Swift" msgstr "" #: ../../source/contributor/contributing.rst:23 msgid "mailing list" msgstr "" #: ../../source/contributor/contributing.rst:24 msgid "" "We use the openstack-discuss@lists.openstack.org mailing list for " "asynchronous discussions or to communicate with other OpenStack teams. Use " "the prefix ``[swift]`` in your subject line (it's a high-volume list, so " "most people use email filters)." msgstr "" #: ../../source/contributor/contributing.rst:29 msgid "" "You can use our `mailing list info page `__ to read the " "archives and subscribe." msgstr "" #: ../../source/contributor/contributing.rst:32 msgid "Contacting the Core Team" msgstr "" #: ../../source/contributor/contributing.rst:34 msgid "" "The swift-core team is an active group of contributors who are responsible " "for directing and maintaining the Swift project. As a new contributor, your " "interaction with this group will be mostly through code reviews, because " "only members of swift-core can approve a code change to be merged into the " "code repository. But the swift-core team also spend time on IRC so feel free " "to drop in to ask questions or just to meet us." msgstr "" #: ../../source/contributor/contributing.rst:42 msgid "" "Although your contribution will require reviews by members of swift-core, " "these aren't the only people whose reviews matter. Anyone with a gerrit " "account can post reviews, so you can ask other developers you know to review " "your code ... and you can review theirs. (A good way to learn your way " "around the codebase is to review other people's patches.)" msgstr "" #: ../../source/contributor/contributing.rst:49 msgid "" "If you're thinking, \"I'm new at this, how can I possibly provide a helpful " "review?\", take a look at `How to Review Changes the OpenStack Way `_." msgstr "" #: ../../source/contributor/contributing.rst:54 msgid "" "Or for more specifically in a Swift context read :doc:`review_guidelines`" msgstr "" #: ../../source/contributor/contributing.rst:56 msgid "" "You can read about the role of core reviewers in the `OpenStack governance " "documentation `_, learn more about the swift-core members in our gerrit " "`membership list `__, " "and also find the team at our `Swift weekly meetings <#communication>`__." msgstr "" #: ../../source/contributor/contributing.rst:64 msgid "Getting Your Patch Merged" msgstr "" #: ../../source/contributor/contributing.rst:65 msgid "" "Understanding how reviewers review and what they look for will help getting " "your code merged. See `Swift Review Guidelines `_ for how we review code." msgstr "" #: ../../source/contributor/contributing.rst:69 msgid "" "Keep in mind that reviewers are also human; if something feels stalled, then " "come and poke us on IRC or add it to our meeting agenda." msgstr "" #: ../../source/contributor/contributing.rst:73 msgid "Project Team Lead Duties" msgstr "" #: ../../source/contributor/contributing.rst:74 msgid "" "All common PTL duties are enumerated in the `PTL guide `_." msgstr ""