• 
      

    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)

    reviewbot reviewbot

    E501 line too long (108 > 79 characters)

    reviewbot reviewbot

    E501 line too long (104 > 79 characters)

    reviewbot reviewbot

    E501 line too long (104 > 79 characters)

    reviewbot reviewbot

    E501 line too long (83 > 79 characters)

    reviewbot reviewbot

    E303 too many blank lines (4)

    reviewbot reviewbot

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

    chipx86 chipx86

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

    chipx86 chipx86

    Can you add a rbgateway-configuration anchor?

    chipx86 chipx86

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

    chipx86 chipx86

    Missing webhookStorePath.

    brennie brennie

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

    chipx86 chipx86

    Do we have a default?

    chipx86 chipx86

    Misisng webhookStorePath

    brennie brennie

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

    chipx86 chipx86

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

    brennie brennie

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

    chipx86 chipx86

    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 …

    chipx86 chipx86

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

    brennie brennie

    Can you add an rbgateway-installation anchor here?

    chipx86 chipx86

    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/). …

    chipx86 chipx86

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

    brennie brennie

    E501 line too long (87 > 79 characters)

    reviewbot reviewbot

    E501 line too long (94 > 79 characters)

    reviewbot reviewbot

    E501 line too long (90 > 79 characters)

    reviewbot reviewbot

    E501 line too long (90 > 79 characters)

    reviewbot reviewbot

    E501 line too long (83 > 79 characters)

    reviewbot reviewbot

    E303 too many blank lines (4)

    reviewbot reviewbot

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

    chipx86 chipx86

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

    chipx86 chipx86

    E501 line too long (87 > 79 characters)

    reviewbot reviewbot

    E501 line too long (94 > 79 characters)

    reviewbot reviewbot

    E501 line too long (90 > 79 characters)

    reviewbot reviewbot

    E501 line too long (90 > 79 characters)

    reviewbot reviewbot

    E501 line too long (83 > 79 characters)

    reviewbot reviewbot

    E303 too many blank lines (4)

    reviewbot reviewbot
    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)