[Starlingx-discuss] Full process to update/add documentation pages (gerrit review push issue)

[Ildiko Vancsa]

Hi Dominig,

There are some plans to make some of the documentation that is currently written up in the OpenStack Contributor Guide to be made available to all OSF projects using OpenDev tooling.

In the meantime please refer to this page for some Git/Gerrit best practices: https://docs.openstack.org/contributors/code-and-documentation/patch-best-practices.html

I don’t think we have strong guidelines when it comes to Gerrit topics. A rule of thumb is to keep it short and informative, people often refer to Launchpad or Storyboard identifiers, like 'bug/<bug_id>’ or ’story/<story_id>’. It really only matters if there are multiple changes that are related but not organized in a chain of patches so you can use the Gerrit topic as a search filter to display all the relevant changes at once.

I hope this helps.

Please let me know if you have further questions.

Thanks,
Ildikó


> On 2019. Sep 12., at 19:43, Dominig ar Foll (Intel Open Source) <dominig.arfoll at fridu.net> wrote:
> 
> On 12/09/2019 18:41, Ildiko Vancsa wrote:
>> Hi Dominig,
>> 
>> Which steps have you performed before trying to upload your commit to Gerrit?
>> 
>> Have you initialized your local repo with ‘git review -s’ for instance after cloning it?
>> 
>> I’m also a little confused by the command in your mail: git review -t "initial creation Doc page Navigate Git Code story/2005184”
>> 
>> ‘-t’ specifies the Gerrit topic which should be not more than for instance 'story/2005184’. It looks like you are trying to add the commit message title to the topic which is a bit too long as topic text.
>> 
>> If you are on IRC (#starlingx channel on Freenode) I can help figuring this out in a more synchronous way.
> OK, it seems that Geoffroy as usual had a great idea to work around the
> issue. Geoffroy thanks your trick of removing spaces, worked.
> 
> When it come to the user of -t, I guessed from the git-review that
> adding a topic would be helpful, but without guidance on documentation,
> I did like what I was doing in AGL.
> 
> So I did clone the documentation repo
>    git clone https://opendev.org/starlingx/docs
>    git clone https://opendev.org/starlingx/specs
> 
> # added my page with my prefered text editor
> # then
>  git commit -sam "initial creation Doc page Navigate Git Code story/2005184"
>  git review -t "initial creation Doc page Navigate Git Code story/2005184"
> # !!oups that did not work. I got a not that helpful error message
>  git review -t "initial_creation_Doc_page_Navigate_Git_Code_story/2005184"
> # that one was accepted with a warning on the length of my topic.
> 
> If someone knows what should actually be done, it would be nice to add it to the documentation on how to improve documentation.
>   https://docs.starlingx.io/contributor/doc_contribute_guide.html
> So far the only guidance is :
>  ...
>  and then submit the changes to Gerrit for approval.
>  ...
> 
> -- 
> Dominig ar Foll
> Senior Software Architect
> Intel Open Source Technology Centre
>