• 
      

    Add a basic user manual for rb-gateway.

    Review Request #10049 — Created June 29, 2018 and submitted

    Information

    rb-gateway
    master
    d7aa4ef...

    Reviewers

    This change adds a user manual for rb-gateway. It includes (very very
    simple) installation instructions, and documentation on how to configure
    and run the service.

    Built HTML and viewed results.

    Description From Last Updated

    E501 line too long (87 > 79 characters)

    reviewbotreviewbot

    E501 line too long (108 > 79 characters)

    reviewbotreviewbot

    E501 line too long (104 > 79 characters)

    reviewbotreviewbot

    E501 line too long (104 > 79 characters)

    reviewbotreviewbot

    E501 line too long (83 > 79 characters)

    reviewbotreviewbot

    E303 too many blank lines (4)

    reviewbotreviewbot

    Can you add an anchor to this? Maybe rbgateway-index? That'll help with linking from the Review Board manual.

    chipx86chipx86

    The "... which can require additional APIs" feels a little redundant. Maybe just get rid of that bit.

    chipx86chipx86

    Can you add a rbgateway-configuration anchor?

    chipx86chipx86

    Rather than ::, this would be better with: .. code-block:: javascript <code here> That'll ensure syntax highlighting is correct.

    chipx86chipx86

    Missing webhookStorePath.

    brenniebrennie

    Definitions should be indented 4 spaces (here and below).

    chipx86chipx86

    Do we have a default?

    chipx86chipx86

    Misisng webhookStorePath

    brenniebrennie

    Above, we don't use colons after the name/type, but we do here. We should be consistent.

    chipx86chipx86

    Might want to mention this is also included as /contrib/rb-gateway.service

    brenniebrennie

    This can, I think, be: .. code-block:: ini <code...>

    chipx86chipx86

    How about a simple /usr/local/bin/rb-gateway and /etc/rb-gateway/? I know some things like /opt/rb-gateway/, but I feel like that's less standard …

    chipx86chipx86

    Can you add: ExecReload=/bin/kill -HUP $MAINPID This allows users to do systemctl reload rb-gateway Also, do you mind adding this …

    brenniebrennie

    Can you add an rbgateway-installation anchor here?

    chipx86chipx86

    I feel like we should provide more guidance here, and we should link to the download page (it'll be https://www.reviewboard.org/downloads/rbgateway/). …

    chipx86chipx86

    It also will need write access to the token store path and the webhook store path

    brenniebrennie

    E501 line too long (87 > 79 characters)

    reviewbotreviewbot

    E501 line too long (94 > 79 characters)

    reviewbotreviewbot

    E501 line too long (90 > 79 characters)

    reviewbotreviewbot

    E501 line too long (90 > 79 characters)

    reviewbotreviewbot

    E501 line too long (83 > 79 characters)

    reviewbotreviewbot

    E303 too many blank lines (4)

    reviewbotreviewbot

    I'm guessing we'd want /etc/rb-gateway/rb-gateway.conf, since there's also a webhooks.conf, right?

    chipx86chipx86

    I realized the flaw with my idea here is that we have a version per platform. So maybe latest/linux_amd64/, which …

    chipx86chipx86

    E501 line too long (87 > 79 characters)

    reviewbotreviewbot

    E501 line too long (94 > 79 characters)

    reviewbotreviewbot

    E501 line too long (90 > 79 characters)

    reviewbotreviewbot

    E501 line too long (90 > 79 characters)

    reviewbotreviewbot

    E501 line too long (83 > 79 characters)

    reviewbotreviewbot

    E303 too many blank lines (4)

    reviewbotreviewbot
    Checks run (1 failed, 1 succeeded)
    flake8 failed.
    JSHint passed.

    flake8

    brennie
    1. 
        
    2. Show all issues

      Missing webhookStorePath.

    3. Show all issues

      Misisng webhookStorePath

    4. Show all issues

      Might want to mention this is also included as /contrib/rb-gateway.service

      1. Seeing as that's part of the git repo and not distributed on the downloads page, I don't think that's a useful thing to mention.

    5. Show all issues

      It also will need write access to the token store path and the webhook store path

    6. 
        
    chipx86
    1. 
        
    2. docs/rb-gateway/index.rst (Diff revision 1)
       
       
       
       
      Show all issues

      Can you add an anchor to this? Maybe rbgateway-index? That'll help with linking from the Review Board manual.

    3. docs/rb-gateway/index.rst (Diff revision 1)
       
       
      Show all issues

      The "... which can require additional APIs" feels a little redundant. Maybe just get rid of that bit.

    4. Show all issues

      Can you add a rbgateway-configuration anchor?

    5. Show all issues

      Rather than ::, this would be better with:

      .. code-block:: javascript
      
         <code here>
      

      That'll ensure syntax highlighting is correct.

    6. docs/rb-gateway/rb-gateway/configuration/index.rst (Diff revision 1)
       
       
       
       
       
       
      Show all issues

      Definitions should be indented 4 spaces (here and below).

    7. Show all issues

      Do we have a default?

    8. Show all issues

      Above, we don't use colons after the name/type, but we do here. We should be consistent.

    9. Show all issues

      This can, I think, be:

      .. code-block:: ini
      
         <code...>
      
    10. Show all issues

      How about a simple /usr/local/bin/rb-gateway and /etc/rb-gateway/? I know some things like /opt/rb-gateway/, but I feel like that's less standard and more prone to confusing people.

    11. Show all issues

      Can you add an rbgateway-installation anchor here?

    12. Show all issues

      I feel like we should provide more guidance here, and we should link to the download page (it'll be https://www.reviewboard.org/downloads/rbgateway/).

      I also think we can do something useful with providing a handy redirect on the site that points to the latest download (say, https://www.reviewboard.org/downloads/rbgateway/latest/), since the URL will be predictable and we know the version information on the server. With that, we can have something like:

      You can `download the latest version`_ of ``rb-gateway`` or view the
      `downloads page`_ for other options. Once downloaded, place the binary
      somewhere on your server (for example, on Linux,
      :file:`/usr/local/bin/rb-gateway`) and make it executable.
      
      You'll also need a place to store the configuration files (for example,
      :file:`/etc/rb-gateway/`).
      
      For example, to get started quickly on Linux:
      
          $ sudo curl https://www.reviewboard.org/downloads/rbgateway/latest/ \
                 -O /usr/local/bin/rb-gateway
          $ sudo chmod +x /usr/local/bin/rb-gateway
          $ sudo mkdir /etc/rbgateway
      

      Once installed, follow the :ref:`configuration instructions <rbgateway-configuration>`
      to finish setting up your server.
      
      1. Technically it should go into /opt since its third party.

      2. Eh, I don't know about that. That's not really done in reality, generally-speaking, and can lead to more confusion than anything. /opt is more often used if you're dealing with a more self-contained installation environment (think a Bitnami install) rather than user-downloadable software.

    13. 
        
    brennie
    1. 
        
    2. Show all issues

      Can you add:

      ExecReload=/bin/kill -HUP $MAINPID
      

      This allows users to do systemctl reload rb-gateway

      Also, do you mind adding this to the unit file as well?

    3. 
        
    david
    Review request changed
    Commit:
    6f3e85f8e45dcaee49993d0341a3149325d0411f
    81d596861655731da229a5fe4b297ce33d6674a5

    Checks run (1 failed, 1 succeeded)

    flake8 failed.
    JSHint passed.

    flake8

    chipx86
    1. Looking good.

    2. Show all issues

      I'm guessing we'd want /etc/rb-gateway/rb-gateway.conf, since there's also a webhooks.conf, right?

    3. 
        
    chipx86
    1. 
        
    2. Show all issues

      I realized the flaw with my idea here is that we have a version per platform. So maybe latest/linux_amd64/, which would map to the rbgateway-1.0-linux-amd64 (or, say, rbgateway-1.0-windows-amd64.exe).

    3. 
        
    david
    Review request changed
    Commit:
    81d596861655731da229a5fe4b297ce33d6674a5
    d7aa4ef639399a694902af6a7d9aa1f10643f935

    Checks run (1 failed, 1 succeeded)

    flake8 failed.
    JSHint passed.

    flake8

    chipx86
    1. Ship It!
    2. 
        
    david
    Review request changed
    Status:
    Completed
    Change Summary:
    Pushed to master (7c56760)