Overview
This page details the steps that ATA undertakes for contributing and reviewing bitbucket contributions.
These practices do not apply to documents being developed in Word, where existing practices will continue to be used. It is up to the Project Stream and Editors as to whether Word or Markdown is used to develop documents for any one project.
These contribution are those targeting a deliverable that is being developed using the BBF Code Tool (Bitbucket).
The ATA Bitbucket Repository can be found here: https://code.broadband-forum.org/projects/ATA
For the ATA Work Area, the deliverable is most likely to be one of the following:
- Documentation that is produced in MarkDown (in preference to the MS Word based approach). The benefit of producing a document in markdown is that it is more web friendly, but the process of doing so using BBF Code (bitbucket/git) allows much more methodical and less error prone way of proposing and reviewing contributions.
- Yang Models or Protocol Buffer Definitions. These are more formally treated as software by the Broadband Forum (Please also see the BBF software project guidance here: https://www.broadband-forum.org/software for important information such as the need to submit a Software submission form)
Process for contributing:
Note: The Develop branch of the Bitbucket repository can be considered as the Baseline Working Text.
1: Identify the Issue
- Create a Jira Issue (for the specific project - not a general contribution) including a description of the issue and the general concepts and approach proposed for resolution.
- The description can be made in the Jira issue itself, it does not mandate an attached document.
- Mark the Jira issue as 'For Review' and it will be scheduled to be discussed at a meeting/call.
- The PS will generally discuss the Jira issue in advance of any changes being contributed (to ensure that the proposed approach is correct) and assign the issue to a user (a contributor could provide code in parallel, but there is a risk that the approach taken might not be agreed with by the group).
- Once the Jira issue has been discussed and accepted, it will be Assigned (normally to the contributor). It may alternatively be rejected by the group at this point.
2: Work on the solution and propose changes
- Create a new user-specific branch of the repository in Bitbucket (following the software projects guidance)
- Make the proposed changes and commit them.
- Automated build / checks will be run by the Bamboo Tool (for example, validation and lint tools)
- Fix any issues and recommit until the build passes.
- Create a Pull Request from the user-specific branch to the 'develop' branch
3a: Review for a Markdown WT
- Mark the issue 'For Review' and it will be scheduled to be discussed at a meeting/call. Note: for small changes this may be the same review as above. It is also good practice to inform the group via the email list.
- Commenters can provide feedback on the PR directly in Bitbucket - including the ability to suggest changes.
- ATA will schedule meeting time to review the PR - comments can be made at this point and are recorded in the PR in bitbucket.
- For a markdown WT, the PR may be accepted at this review, or may sent back for more work.
3b: Review for a YANG Model
- In addition to 3a above, a yang model Pull Request also requires at least one formal 2 week yang review.
- This is initiated by the PS lead sending an email to the ATA list copying yang-advisors@broadband-forum.org and yang@broadband-forum.org which will include the YANG Advisors and Common YANG in the review)
- YANG comments are always made directly in Bitbucket in all cases, as they are generally detailed technical and formatting specific comment
- At the close of the review period, if there are no unresolved comments (and the reviewers have approved the PR), the PR can be merged to the develop branch.