Details

    • Type: Bug
    • Status: Resolved
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 1.0 Beta
    • Component/s: docs
    • Security Level: Public
    • Labels:
      None

      Description

      For the upcoming 1.0 Python client, we'll need to come up with a TOC. Likely something like MB-7714.

        Issue Links

        No reviews matched the request. Check your Options in the drop-down menu of this sections header.

          Activity

          Hide
          kzeller kzeller added a comment -

          Not sure who is the subject matter expert on Python but we need input on the topics. Here is the TOC for Java-next-gen:

          1. Getting Started
          1.1 Preparations
          1.2 Hello Couchbase
          1.3 Next Steps

          2. Tutorial
          2.1 Preparations
          2.2 Quickstart
          2.3 Connection Management
          2.4 The Welcome Page
          2.5 Managing Beers
          2.6 Wrapping Up

          3. Using the APIs
          3.1 Connection Management
          3.2 Retreiving Data
          3.3 Mutating Data
          3.4 Working with Views
          3.5 Applying Persistence Constraints
          3.6 Error Handling
          3.7 JSON & Object Serialization
          3.8 Design Document Management

          4. Advanced Usage
          4.1 Bulk Loading
          4.2 Working with Documents
          4.3 Advanced Topics
          4.4 Logging & Debugging

          5. API Reference
          5.1 Method Summary
          5.2 Connecting & Disconnecting
          5.3 Retreiving Data
          5.4 Mutating Data
          5.5 Management Operations
          5.6 Other Useful Operations

          A. Release Notes
          B. Contributing
          B.1 General Information
          B.2 Source Code Styleguide

          Show
          kzeller kzeller added a comment - Not sure who is the subject matter expert on Python but we need input on the topics. Here is the TOC for Java-next-gen: 1. Getting Started 1.1 Preparations 1.2 Hello Couchbase 1.3 Next Steps 2. Tutorial 2.1 Preparations 2.2 Quickstart 2.3 Connection Management 2.4 The Welcome Page 2.5 Managing Beers 2.6 Wrapping Up 3. Using the APIs 3.1 Connection Management 3.2 Retreiving Data 3.3 Mutating Data 3.4 Working with Views 3.5 Applying Persistence Constraints 3.6 Error Handling 3.7 JSON & Object Serialization 3.8 Design Document Management 4. Advanced Usage 4.1 Bulk Loading 4.2 Working with Documents 4.3 Advanced Topics 4.4 Logging & Debugging 5. API Reference 5.1 Method Summary 5.2 Connecting & Disconnecting 5.3 Retreiving Data 5.4 Mutating Data 5.5 Management Operations 5.6 Other Useful Operations A. Release Notes B. Contributing B.1 General Information B.2 Source Code Styleguide
          Hide
          ingenthr Matt Ingenthron added a comment -

          Mark ist he SME.

          Mark: Using this as a base (unless you have feedback to the contrary), can you edit up a TOC for the Python 1.0 release in this ticket?

          Show
          ingenthr Matt Ingenthron added a comment - Mark ist he SME. Mark: Using this as a base (unless you have feedback to the contrary), can you edit up a TOC for the Python 1.0 release in this ticket?
          Hide
          mnunberg Mark Nunberg added a comment - - edited

          I'd probably want to nix (for now):

          2.3 Connection Management (it's a simple object, there's no global pooling yet)
          3.4 Views (we don't have a stable view API yet)
          3.8 ""
          3.5 ""
          4.4 We don't have any significant logging infrastructure in the SDK

          We might want to split 'Preparations' into 'Installing the SDK' and 'Installing the cluster'

          Thus:
          --------------------------------------------------------------------------------------------------------------------------
          1. Getting Started
          1.1 Setting up the cluster
          1.2 Installing the SDK
          1.3 Hello Couchbase
          1.4 Next Steps

          2. Tutorial
          2.1 Preparations
          2.2 Quickstart
          2.3 Connection Management
          2.4 The Welcome Page
          2.5 Managing Beers
          2.6 Wrapping Up

          3. Using the APIs
          3.1 Connecting
          3.2 Retreiving Data
          3.3 Mutating Data
          3.4 Working with Views [ NYI (Not Yet implemented) ]
          3.5 Applying Persistence Constraints [ NYI ]
          3.6 Error Handling
          3.7 JSON & Object Serialization
          3.8 Design Document Management [ NYI ]

          4. Advanced Usage
          4.1 Bulk Loading
          4.2 Notes for using with (and without) threads (maybe this belogns in advanced)?
          4.3 Working with Documents
          4.4 Advanced Topics
          4.5 Logging & Debugging

          5. API Reference
          5.1 Method Summary
          5.2 Initialization
          5.3 Retreiving Data
          5.4 Mutating Data
          5.5 Management Operations
          5.6 Other Useful Operations

          A. Release Notes
          B. Contributing
          B.1 General Information
          B.2 Source Code Styleguide

          Show
          mnunberg Mark Nunberg added a comment - - edited I'd probably want to nix (for now): 2.3 Connection Management (it's a simple object, there's no global pooling yet) 3.4 Views (we don't have a stable view API yet) 3.8 "" 3.5 "" 4.4 We don't have any significant logging infrastructure in the SDK We might want to split 'Preparations' into 'Installing the SDK' and 'Installing the cluster' Thus: -------------------------------------------------------------------------------------------------------------------------- 1. Getting Started 1.1 Setting up the cluster 1.2 Installing the SDK 1.3 Hello Couchbase 1.4 Next Steps 2. Tutorial 2.1 Preparations 2.2 Quickstart 2.3 Connection Management 2.4 The Welcome Page 2.5 Managing Beers 2.6 Wrapping Up 3. Using the APIs 3.1 Connecting 3.2 Retreiving Data 3.3 Mutating Data 3.4 Working with Views [ NYI (Not Yet implemented) ] 3.5 Applying Persistence Constraints [ NYI ] 3.6 Error Handling 3.7 JSON & Object Serialization 3.8 Design Document Management [ NYI ] 4. Advanced Usage 4.1 Bulk Loading 4.2 Notes for using with (and without) threads (maybe this belogns in advanced)? 4.3 Working with Documents 4.4 Advanced Topics 4.5 Logging & Debugging 5. API Reference 5.1 Method Summary 5.2 Initialization 5.3 Retreiving Data 5.4 Mutating Data 5.5 Management Operations 5.6 Other Useful Operations A. Release Notes B. Contributing B.1 General Information B.2 Source Code Styleguide
          Hide
          mnunberg Mark Nunberg added a comment -

          Assigning back to you for review

          Show
          mnunberg Mark Nunberg added a comment - Assigning back to you for review
          Hide
          ingenthr Matt Ingenthron added a comment -

          In response to your comments...

          > 2.3 Connection Management (it's a simple object, there's no global pooling yet)

          True, but there is a discussion here about to create and manage connection objects. I think that's critical to mention, if only a few paragraphs.

          > 3.4 Views (we don't have a stable view API yet)

          True, but we will have by 1.0.

          > 3.8 ""

          Yeah, if this isn't in 1.0, that's fine to leave it out.

          > 3.5 ""

          This will be needed for 1.0, so it should be in.

          > 4.4 We don't have any significant logging infrastructure in the SDK

          Okay to leave it out for now then, sure. Should there be a mention about logging in this section though?

          Show
          ingenthr Matt Ingenthron added a comment - In response to your comments... > 2.3 Connection Management (it's a simple object, there's no global pooling yet) True, but there is a discussion here about to create and manage connection objects. I think that's critical to mention, if only a few paragraphs. > 3.4 Views (we don't have a stable view API yet) True, but we will have by 1.0. > 3.8 "" Yeah, if this isn't in 1.0, that's fine to leave it out. > 3.5 "" This will be needed for 1.0, so it should be in. > 4.4 We don't have any significant logging infrastructure in the SDK Okay to leave it out for now then, sure. Should there be a mention about logging in this section though?
          Hide
          mnunberg Mark Nunberg added a comment - - edited

          Most of the relevant logging would be inside libcouchbase – which doesn't really support logging yet. I guess with the packet queue fixes this should be doable, though; but that's fairly ahead.

          Show
          mnunberg Mark Nunberg added a comment - - edited Most of the relevant logging would be inside libcouchbase – which doesn't really support logging yet. I guess with the packet queue fixes this should be doable, though; but that's fairly ahead.
          Hide
          kzeller kzeller added a comment -

          TOC Review Feedback:

          "3.5 Applying Persistence Constraints [ NYI ] “

          I suppose you will be talking about the “PersistTo and ReplicateTo” parameters.

          What is the correct “word” for this, I see persistence constraints, persistence requirement, or even durability:
          http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-set-durability.html
          http://www.couchbase.com/docs/couchbase-sdk-net-1.2/couchbase-sdk-net-store-set.html

          Just to be sure with use the same all the time

          [CHANGED TO "Durability Requirements"]

          Show
          kzeller kzeller added a comment - TOC Review Feedback: "3.5 Applying Persistence Constraints [ NYI ] “ I suppose you will be talking about the “PersistTo and ReplicateTo” parameters. What is the correct “word” for this, I see persistence constraints, persistence requirement, or even durability: http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-set-durability.html http://www.couchbase.com/docs/couchbase-sdk-net-1.2/couchbase-sdk-net-store-set.html Just to be sure with use the same all the time [CHANGED TO "Durability Requirements"]
          Hide
          ingenthr Matt Ingenthron added a comment -

          To Mark's comments:
          That's fair, but look at it from a user perspective. Maybe we just need to state there is no logging in the python client and logging of most cases with Python is typically handled by the platform it's running on, flask, etc. Then the developer should just know to/how to log return values that don't make sense.

          It's worth a discussion just so a user wondering about logging knows what they need to do.

          Show
          ingenthr Matt Ingenthron added a comment - To Mark's comments: That's fair, but look at it from a user perspective. Maybe we just need to state there is no logging in the python client and logging of most cases with Python is typically handled by the platform it's running on, flask, etc. Then the developer should just know to/how to log return values that don't make sense. It's worth a discussion just so a user wondering about logging knows what they need to do.
          Hide
          ingenthr Matt Ingenthron added a comment -

          Reviewed with Mark, and we've settled on this. We'll open the ticket on delivering the pieces for the next step.


          1. Getting Started
          1.1 Setting up the cluster
          1.2 Installing the SDK
          1.3 Hello Couchbase
          1.4 Next Steps

          2. Tutorial
          2.1 Preparations
          2.2 Quickstart
          2.3 Connection Management
          2.4 The Welcome Page
          2.5 Managing Beers
          2.6 Wrapping Up

          3. Using the APIs
          3.1 Connecting
          3.2 Retreiving Data
          3.3 Mutating Data
          3.4 Working with Views [ in review ]
          3.5 Error Handling
          3.6 JSON & Object Serialization
          3.7 Design Document Management

          4. Advanced Usage
          4.1 Bulk Loading
          4.2 Notes for using with (and without) threads (maybe this belogns in advanced)?
          4.3 Working with Documents
          4.4 Advanced Topics
          4.5 Logging & Debugging

          5. API Reference (this will not be in the docbook docs, but we'll check that all of these are covered in the python generated docs)
          5.1 Method Summary
          5.2 Initialization
          5.3 Retreiving Data
          5.4 Mutating Data
          5.5 Management Operations
          5.6 Other Useful Operations

          A. Release Notes
          B. Contributing
          B.1 General Information
          B.2 Source Code Styleguide

          Show
          ingenthr Matt Ingenthron added a comment - Reviewed with Mark, and we've settled on this. We'll open the ticket on delivering the pieces for the next step. 1. Getting Started 1.1 Setting up the cluster 1.2 Installing the SDK 1.3 Hello Couchbase 1.4 Next Steps 2. Tutorial 2.1 Preparations 2.2 Quickstart 2.3 Connection Management 2.4 The Welcome Page 2.5 Managing Beers 2.6 Wrapping Up 3. Using the APIs 3.1 Connecting 3.2 Retreiving Data 3.3 Mutating Data 3.4 Working with Views [ in review ] 3.5 Error Handling 3.6 JSON & Object Serialization 3.7 Design Document Management 4. Advanced Usage 4.1 Bulk Loading 4.2 Notes for using with (and without) threads (maybe this belogns in advanced)? 4.3 Working with Documents 4.4 Advanced Topics 4.5 Logging & Debugging 5. API Reference (this will not be in the docbook docs, but we'll check that all of these are covered in the python generated docs) 5.1 Method Summary 5.2 Initialization 5.3 Retreiving Data 5.4 Mutating Data 5.5 Management Operations 5.6 Other Useful Operations A. Release Notes B. Contributing B.1 General Information B.2 Source Code Styleguide

            People

            • Assignee:
              ingenthr Matt Ingenthron
              Reporter:
              ingenthr Matt Ingenthron
            • Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Gerrit Reviews

                There are no open Gerrit changes