From this thread on dev@:

I think it is important for the resource requirements to be documented somewhere.

In my testing (using CentOS 7.4 and 7.6) I have found the minimum requirements to be as follows. Not sure this is official, but I was running into resource constraints with anything lower than this amount of resources.

• Kernel: 3.10.0-862.14.4

• CPU: 8 vCPU

• RAM: 32GB

• Root Drive: 60GB

We should document this somewhere (or multiple somewheres).

Migrated from GitHub Issue: #26

I'm creating a summary of this for someone who asked, so I may as well add it into the repo to help everyone.

The summary will:

• Give brief definitions of each group in the community, w/references to the gov docs
• Give brief definitions of each group in the governance, w/references to the gov docs
• Add an acronym reference
• Link to the Election Mechanics in the wiki

It's s a Jira ticket about creating Jira tickets. It's a meta-Jira-ticket! Anyway, we're going to have opinions on how people do this, so we need to document them. This should be linked in a few places (contributor guide, website at the very least).

Items to cover:

• How to log in
• The required fields for a bug report
• Content expectations for each of the required fields
• How to follow up on a bug report you've opened (add comments to the ticket, email a ticket link to the dev@ list)

Gerrit uses 'gates' (tests) to determine whether a patch can be merged. As of today (2019-05-09), the gates are as follows:

Finally debugged the issue and now commits are blocked by requiring an "Issue-ID: " in the commit body

Eventually the gates may be different for each project, but this is a good start and we should start documenting this now.

Current gates that exist in Gerrit:

• Ticket required

When reviewing the current structure of the documentation, I didn't see a good place to put proposals. Where should this governance proposal live?Should we review and comment in Confluence / JIRA

I proposed the following documentation:
https://wiki.tungsten.io/x/YQALAQ

We've received a ppt file full of TF diagrams. We need to save these things for posterity and try to get them incorporated into the docs somehow. The file is larger than Jira will allow me to attach, so here's a Dropbox link to it: https://www.dropbox.com/s/btasyx7thaunbqd/TF%20Diagrams%202.pptx?dl=0

Someone updated review.opencontrail.org to the latest Gerrit. That means that you can't find the access groups under People anymore, since that link doesn't exist. Instead, go to Browse & Groups. The docs need to be updated to reflect this change.

Documentation to capture the release verison info of DPDK (from upstream), which is expected to work with Tungsten Fabric. Compilation instructions to use upstream DPDK libraries.

With our limited resources, we need to focus our resources on the minimal viable product (MVP) for docs. In the 2020-01-09 docs meeting: https://wiki.tungsten.io/display/TUN/2020-01-09+Docs+Project+Meeting we came up with a first pass at a list of things we'll need for that MVP.

Please note a few things:

We're focusing on the point of view of a contributor.                  
Because the docs repo is the only one that's fully moved to the git/gerrit/jira workflow, we'll use it as the target for all of our work.
Because of that, then, we'll be writing for a tech writer audience. Specifically, the Juniper Networks tech writers, since they have the most information about and experience with the product. These people are intelligent and accomplished but don\u0027t use git or reStructuredText for their jobs.

So, our audience are tech writers who don't know git, gerrit, or rST. The documents we create therefore will be a bit lower level than if we were targeting only developers, but even developers will benefit from them. For instance, this level of documentation would have been invaluable for our Google Summer of Code interns in 2019.

Our goal is to have these docs done by mid-2020 (if not sooner) so we can host a training/doc-a-thon in the Juniper offices in June or July.

The index.rst for Governance reads:
Elections
The Election Mechanics wiki page supplements the Charter and Governance Document with specific details such as tools, timelines and exact process details. Changes to this page must be approved by the TSC, but should not contradict anything in either the Charter or Governance Document.

Because it needs to be approved by the TSC, and because it's an important part of governance, it should be in the repo along with the rest of the governance docs.

We should be open about this sort of information, if only so community members know where to go if there are problems.

Currently, the Jira workflows and Blueprint submission process for developers are documented in Google Docs.

https://docs.google.com/document/d/1UWIzZZOzTR8zZeTUOpV5pPzq1EcCPrS-F2GkYysOpR8/edit?usp=sharing
https://docs.google.com/document/d/1hYhaPmQEN4V4ZeLxruloIshnQ6yd05vNkcKqhRqCnIw/edit#heading=h.h3vxu6qloos

For consistency and to allow new developers to easily find this required documentation, the purpose of this task is to move these documents to the required format in the docs repository in the Contributor folder.

https://gerrit.tungsten.io/r/admin/repos/docs&quot

Create a document introducing how to use Gerrit for people who've never seen Gerrit before. Assume a tech writer audience.

There's a link to the Community Governance Document on the Governance page (http://docs.tungsten.io/en/latest/governance/index.html) http://docs.tungsten.io/en/latest/governance/index.html This link is broken and goes to the RTD 404 page.

Re-jigger tungsten.io to move docs currently under 'website' repo 'docs' repo

Migrated from GitHub Issue: #30

According to a conversation in #dev on Slack, the CI process right now is tribal knowledge. This makes it very difficult for contributors to troubleshoot issues or even to know how things are going.

We should start documentation of this process, written from the perspective of the end user (contributor).

The Slack conversation from on/around 2019-01-30:

17:58 vsinitsyn Is everything okay with the CI? 2 minutes for green unit tests doesn't sound real, especially if building centos packages fails: https://review.opencontrail.org/#/c/48958/ (edited)
18:03 VM (Vicky) Brasseur @vsinitsyn A Codilime dev is doing some work on the Gerrit/repos. Maybe that's affecting it?
18:04 VM (Vicky) Brasseur I've emailed him to ask, and also asked him to join the Slack.
18:04 VM (Vicky) Brasseur His name is Jarek, so keep an eye out for him joining.
18:09 vsinitsyn Thanks Vicky will do
18:22 andrey-mp @vsinitsyn CI doesn't re-run UT job if it was successful for this patchset
18:25 VM (Vicky) Brasseur Is there a doc somewhere that covers this stuff? Or is it tribal knowledge?
18:25 vsinitsyn @Andrey-mp good news, thanks
18:28 andrey-mp I've checked job log and made such conclusion
18:30 jluk False alarm
18:30 jluk Pure tribal knowledge.
18:33 VM (Vicky) Brasseur Hrm. That's not gonna scale.
18:34 — VM (Vicky) Brasseur opens a doc issue…

We should be open about this sort of information, if only so community members know where to go if there are problems.
See this thread for information on dev ML moderators.
Who are the moderators for the other lists?

This spreadsheet lists all of the TF services and the ports that they listen on and talk to: https://docs.google.com/spreadsheets/d/14IGWcfZLJhG0nz6iSZGpRqKz4PajqHohH6HG__vVsnA/edit?usp=sharing We should convert this into an rST doc.

Creative Commons has come out with a styleguide and it's (no surprise) licensed CC BY: https://creativecommons.org/wp-content/uploads/2019/10/Creative-Commons-Style-Guide-2019.pdf&quot Maybe this is something we could fork as modify to become our first styleguide?

Migrated from GitHub Issue: #21

From #docs on Slack today (2019-01-11):

00:13 I would like to install tungsten fabric with openstack queens manually.
00:13 But I can't find any documents about that.

And also in #users:

07:29 I would like to integrate tungsten fabirc with openstack (queens, rocky) . But I don't see any documents for manual install.
07:32 @Sapd I don't know about any docs that describes how to configure installed OpenStack with new deployed TF
07:34 Today I have installed TF on Kubernetes. But I would like to manual install to clear understand about architecture and all components
08:11 you need to provide keystone auth params to TF of existing OpenStack
08:13 in OpenStack you need to run compute/neutron/heat containers to bring required binaries/modules and then you need to configure neutron/heat
08:15 I will check contrail-heat

The TSC has spoken: The tf-docs repo will act as a prototype for transitioning all TF repos from Gerrit to GitHub. This issue is for tracking the work related to this transition for tf-docs.

• Confirm all patches are landed from Gerrit
• Set core contributors as GH repo owners
• Set confirm only owners can merge
• Add repo topics (a GH thing)
• Disable issues, wiki, other unused repo stuff
• Disable mirroring from Gerrit
• Move CLA process to GH
• Set up previewstaging RtD
• Set up gates
• Require Issue ID
• Successful staging push
• rST linter
• GH status check: strict (this is the default behavior)
• Require two +1s
• Disallow patches directly to master
• Confirm patches update Jira
• Disable Gerrit (stop accepting patches)

This spreadsheet lists all of the TF services and the ports that they listen on and talk to: https://docs.google.com/spreadsheets/d/14IGWcfZLJhG0nz6iSZGpRqKz4PajqHohH6HG__vVsnA/edit?usp=sharing We should convert this into an rST doc.

Dmitri at Juniper is working on a Carbide Evaluation Guide (aka CEG) for TF. It';s target audience is people who are familiar with Kubernetes and its goal is to make it easier for k8s folks to get up to speed with TF. Right now the document is in a Google Doc: https://docs.google.com/document/d/1RDwLfcZkZfP_b2MDrxIyl3zsy0UrQEErZAStI_Mvv08/edit Once the initial work is complete, the CEG will have to move to the https://gerrit.tungsten.io/r/admin/repos/docs It should go into the User/GettingStarted directory. It must be in http://docutils.sourceforge.net/rst.html

Will assembled the Docs Census, collecting the diaspora of TF documentation in one spot (well links to the docs, anyway):
https://wiki.tungsten.io/display/TUN/Docs+Census

We should review this census to see whether there are any items in there that can be used for the MVP.

The read the docs site has the manual CLA steps for the original OpenContrail Gerrit. https://tungsten-fabric-documentation.readthedocs.io/en/latest/manual-cla-admin.html It appears we need to document the automated CLA process. Although it's straight forward, it would be helpful to have clear steps in read the docs. Wills Docs Census has a description. https://wiki.tungsten.io/display/TUN/Docs+Census It should just require a conversion to RST and to the contributor docs.

Here are some screenshots to use when documenting the easyCLA step of contributing:

Tungsten Fabric requires release notes for the r5.1 release. This ticket is for the submission of the r5.1 release notes into the appropriate ReadTheDocs (RTD) format.

• Confirm all patches are landed from Gerrit
• Set core contributors as GH repo owners
• Set/confirm only owners can merge
• Add repo topics (a GH thing)
• Disable issues, wiki, other unused repo stuff

Many tech writers arent very familiar with git. We should create a basic doc for this so they have the resources they need to get started.
We can rely on existing resources out there in the world for some of this. For instance, recently (past few years) the Write The Docs conference held a git for tech writers workshop. If those materials are available we may be able to repurpose them (depending upon their licensing).

Work we'd like to tackle during the 2019 DDF at KubeCon in San Diego

We should document tha basic CI/CD workflow for TF. For now we can start with the workflow for the Docs repo. We can information about other repos as it materialises.

page: https://tungstenfabric.github.io/website/Tungsten-Fabric-Ubuntu-one-line-install-on-k8s.html

Section:

What just happened ?
Hurray! Welcome to Tungsten Fabric.

You installed Tungsten Fabric CNI in your Kubernetes node. If new compute nodes are added to your Kubernetes cluster, Tungsten Fabric CNI will be propogated to them auto-magically as it is backed by a Kubernetes DaemaonSet.

An extra sentence should be added to clarify what happens to compute nodes which have already been added prior to this command.

Reading that sentence it kind of sounds like the CNI will only apply from now on, but based on my understanding of daemonsets I would expect that it is already applied to those.

Should I not have added my compute nodes yet when setting up my cluster?

A bit of disambiguation would be good.

We now have the automated CLA stuff integrated into gerrit.tungsten.io.

The docs team will be the first using this Gerrit, which will give us a good opportunity to test out the CLA stuff and ensure it's documented, making contributions easier for others once their repos transition to the TF Gerrit.

A potentially helpful reference will be the LF CLA documentation: https://docs.linuxfoundation.org/display/DOCS/Contributor+License+Agreement+User+Guide

Migrated from GitHub Issue: #31

From #dev on Slack (on/around 2019-02-20):

05:10 Hello everyone. Can somebody help me with updating schemas? My question is what packages needed to be reinstalled after schema updating. For example, if i want to update this file - https://github.com/Juniper/contrail-controller/blob/R4.0/src/schema/loadbalancer.xsd
And another example - if i want to make changes in schema - do i need to change something in other files?

Many contributors (tech writers, programmers, others) wont be familiar with rST. We should provide basic guidance for how to use it.

Migrated from GitHub Issue: #32

From the #users channel on Slack (on/around 2019-02-21):

11:41 Hi all,
11:41 quick question
11:41 on which smart NICs is vRouter offload supported?
11:41 https://tungstenfabric.github.io/website/Tungsten-Fabric-Architecture.html#smartnic-vrouter
12:04 mellanox and neutronome I suppose. both companies worked on supporting theier products. but i don't know exact version where it works

Add a quick start guide for using Tungsten Fabric using TF-Devstack and upgrades for Contrail Ansible deployer - k8 and Openstack.

Add Configuration API Guide to cover the followings.:

1. Overview
2. REST API (with examples)
3. Python API (with examples)

For now this will only list the core committers (+2/merge) folks for the Docs project and repo, but eventually we'll add the others in there as well after they move to the TF gerrit.

Instead, maybe document the merge requirements then link to a wiki page listing the current core committers for each project?

TF must obey the same CoC that applies to all LF projects: https://lfprojects.org/policies/code-of-conduct/ We should make sure that this CoC is linked everywhere (docs repo, all other repos, websites, wiki, slack).

Right now this doc is accidentally in the root directory. It should be under administration. Also, it's not showing in RTD at all. This may be a result of the prior sync issues, but more likely it needs to be added to an index.rst or some such?

Migrated from GitHub Issue: #20

From #users on Slack today (2019-01-10):

12:12 Hello All, can someone let me know if @tf can be used as a SD-WAN solution similar to Viptela or Velo Cloud for enterprise branch connectivity – any links to documentation to such implementation if any would be very helpful, Thanks in advance

Once CI is in place, we should be requiring docs be updated when code changes. This ticket can be a placeholder for discussion around such an issue.

Add a quick start guide for using Tungsten Fabric as a container network interface for Kubernetes deployments https://jira.tungsten.io/browse/TFB-1465 GSoC TF as a CNI for K8s guide

Here are notes I took while setting up git-review and sending my first patch (for https://jira.tungsten.io/browse/TFB-1412 ) They need to be cleaned up, converted to .rst, and added to the Contributors directory.

• Confirm you have a Jira ticket for the work (required for commit)
• Confirm you have a signed CLA?
  • Gerrit > Settings > Agreements > New Contributor Agreement OR
  • https://contributor.lfcla.com/#/login
  • Should be directed to this first time you try to do a git-review?
• Clone the repo (if you don’t have it yet)
  • Log into gerrit.tungsten.io
  • Click Browse > Repositories
  • Select the repo you want
  • git clone "ssh://[email protected]:29418/docs"
• Set up SSH access for Gerrit (required for the scp in the next step)
  • Log into gerrit.tungsten.io (if you’re not already)
  • Click the ‘Settings’ gear in the upper right next to your name
  • Click ‘SSH Keys’
  • Add your public SSH key (.pub)
  • Test: ssh -p 29418 [email protected] gerrit version
  • Should be gerrit version 2.16.8 or higher
• Set up git-review
  • References
    • section 4.2: https://github.com/tungstenfabric/docs/blob/master/Contributor/GettingStarted/getting-started-with-tungstenfabric-development.md
    • https://docs.openstack.org/infra/git-review/
    • https://www.mediawiki.org/wiki/Gerrit/git-review
  • pip install —user git-review
  • Update path to include git-review ($HOME/Library/Python/2.7/bin on macOS; ~/.local/bin on Ubuntu thanks to that --user in the pip command)
  • export PATH=$HOME/Library/Python/2.7/bin:$PATH <— .bash_profile
  • cd $repo
• Set git config for the repo
  • git config user.email [email protected]
  • gitdir=$(git rev-parse --git-dir);
  • scp -p -P 29418 [email protected]:hooks/commit-msg ${gitdir}/hooks (necessary? cloned w/hooks above)
  • git remote add gerrit ssh://[email protected]:29418/docs
  • git review -s (tests the setup; success == no messages)
• Make necessary changes
• Commit your changes
  • Use commit -s so you’ll get the signed-off-by, which is required by git review
  • If you forget to sign a commit, run git commit --amend -s -c <SHA> on it
• Run git review to get the patch into Gerrit
  • git review

Success looks something like this:
`Θυια:docs vmb$ git review

remote:

remote: Processing changes: }}{{new: 1 ()

remote: Processing changes: new: 1 (|)

remote: Processing changes: new: 1

remote: Processing changes: new: 1

remote: Processing changes: new: 1 ()

remote: Processing changes: refs: 1, new: 1 ()

remote: Processing changes: refs: 1, new: 1, done

remote:

remote: SUCCESS

remote:

remote: New Changes:

remote: https://gerrit.tungsten.io/r/c/docs/+/24 Reorg docs directories

To ssh://gerrit.tungsten.io:29418/docs

• [new branch] HEAD -> refs/for/master
  `

Once the Deprecation Policy is approved, we'll be moving this to the docs repo: https://wiki.tungsten.io/pages/viewpage.action?pageId=10060530

;Right now the docs have a Public Meetings page: http://docs.tungsten.io/en/latest/index.html#public-meetings It duplicates info available in the wiki or would, if it weren't already out of date. Instead of duplicating the info here, instead link to the appropriate places on the wiki.

We don't really have an entry point/landing page for contributing.

There's some stuff on the website, and some stuff in the repo, and some stuff scattered around elsewhere (see the Docs Census: https://wiki.tungsten.io/display/TUN/Docs+Census

We need to create a single, easy to find and use landing page in RTD for all of this information.

Right now there's no way to see who's a member of which working group. We should add these to the docs.

Instead of documenting the members themselves (since membership can change a lot), instead doc what the standing WGs are and link to the wiki pages for them.

A checklist of things we have to do after a TSC election. Please update this list accordingly here until the doc exists:

• Update Dockerhub Owners (all TSC members are owners)
• Update TSC wiki page
• Update website