diff --git a/.gitignore b/.gitignore index e35d8850c9688b1ce82711694692cc574a799396..6a35bdace76e6166634820391e0681d8816a694a 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ -_build +_build*/ +local/ diff --git a/01-workflow-osm-tools.md b/01-workflow-osm-tools.md index ea35f604b6bbb4a0a112bf00378f8899f36590ce..839f3e0236c61e3fbd8e0c0a0bf7c2753f7e38b1 100644 --- a/01-workflow-osm-tools.md +++ b/01-workflow-osm-tools.md @@ -2,6 +2,8 @@ ## Login to OSM portal +To be able to use all the tools required in the development cycle, you need to be authenticated in ETSI portal + 1. Go to OSM portal: 2. Log in using your username and password @@ -24,7 +26,9 @@ If you need any help, contact us at 6. Click on the "Submit Bug" button to confirm. 7. A bug id is generated (e.g. Bug 6 -Small Error) -## Clone your project +## Contributing code + +### Clone your project 1. Clone a git repository, for example: ```bash @@ -57,7 +61,7 @@ More information about the Gerrit commit-msg hook can be found [here](https://gi 3. Click on "List" menu. 4. Select a product to see the available cloning URLs. -## Configure your Git environment +### Configure your Git environment 1. Configure your git username globally: ```bash @@ -87,11 +91,11 @@ git config --local user.name git config --local user.email ``` -## Python 3 +### Python 3 New Python contributions to Open Source Mano must support Python 3+. Python 2.7 reaches an End of Life status on 1 January 2020 and will no longer be supported with bug fixes or security patches. -## License Headers +### License Headers Newly contributed Source Code should be licensed under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0). A [LICENSE](https://osm.etsi.org/gitweb/?p=osm/LCM.git;a=blob_plain;f=LICENSE;hb=HEAD) file shall exist at the root of the repository and all source files should have the following LICENSE header: @@ -130,7 +134,7 @@ Please update the template’s first line # Copyright 2020 MyOrgName Inc ``` -## Commit changes to your local project +### Commit changes to your local project 1. Go to the "RO" folder ```bash @@ -150,7 +154,7 @@ Please update the template’s first line git commit --amend ``` -### Developer's Certificate of Origin +#### Developer's Certificate of Origin - The `-s` parameter enables to Sign the contribution. It adds the following line at the end of your commit message: @@ -188,9 +192,9 @@ Please update the template’s first line this project or the open source license(s) involved. ``` -## Push your contribution to Gerrit +### Push your contribution to Gerrit -### Push your contribution to Gerrit using `git push` +#### Push your contribution to Gerrit using `git push` 1. To avoid merge conflicts, it is recommended to do a pull with rebase before pushing your contribution in order to merge latest changes made by other users. ```bash @@ -220,7 +224,7 @@ Please update the template’s first line - **Gerrit** reports the new contribution state to the corresponding bug in **Bugzilla** - **Gerrit** notifies **Jenkins** to build the new contribution. -### Push your contribution to Gerrit using git review +#### Push your contribution to Gerrit using git review Instead of using "git push", you could use "git review". Follow this guide ([Using git-review to push and review changes](05-git-review.md)) to install and configure `git-review`. You will also have to set the SSH URL for your remote and copy the `commit-msg` hook. @@ -233,7 +237,7 @@ Instead of using "git push", you could use "git review". Follow this guide ([Usi git review -c ``` -## Gerrit Notifications +### Gerrit Notifications Gerrit sends email notifications to: @@ -245,17 +249,17 @@ Each user can configure his own watched projects and branches in the "settings/w Link: (you can navigate there from the Gerrit console by clicking on the arrow by your login on the top right corner) -## Continuous Integration +### Continuous Integration 1. **Jenkins** builds, tests the new contribution, and reports the result on its web interface. 2. **Jenkins** votes on the contribution using **“Code-Verif”** (-1, +1) on **Gerrit**. -## Code Review +### Code Review 1. Other **contributors** and **MDG Committers** can comment the new contribution and vote using **“Code-Review”** (-1, 0, +1) on **Gerrit**. 2. The **MDG Leader** can comment the new contribution and votes using **“Code-Review”** (-2, -1, 0, +1, +2) on **Gerrit**. -## Code Merging +### Code Merging Code submitted to Gerrit, will be merged only after getting - Code Review >= +2 @@ -311,7 +315,7 @@ with subject `[TSC APPROVAL] {change summary}` indicating in body TSC wil review, and provide `Code Review: +2` if approved. -## Amending a contribution in Gerrit +### Amending a contribution in Gerrit Before amending, make sure that you have the commit-msg hook installed in your local repo. For instance, if your user is "user" and the repo is the "devops" repo, the command to install the commit-msg hook would be: @@ -323,7 +327,7 @@ In that way, all patches will use the same Change Id, thus guaranteeing that the NOTE: If you don't setup your environment as above, and would like to update a gerrit review with your new/updated code, you MUST have the Change-Id (of the existing gerrit review) inside the commit message. If the commit update does not contain the Change-Id, the commit will will end up creating a new gerrit review, and your subsequent gerrit review will need to be abandoned (not ideal). -### Amending your last change/commit pushed to Gerrit +#### Amending your last change/commit pushed to Gerrit 1. Get the latest changes from the repo and rebase your changes on top. ```bash @@ -343,7 +347,7 @@ NOTE: If you don't setup your environment as above, and would like to update a g git push origin HEAD:refs/for/master ``` -### Amending one of your changes which has dependencies on subsequent changes +#### Amending one of your changes which has dependencies on subsequent changes This procedure will only work if you are the only person working on a set of commits and you don't expect others to push commits and rebase them to be dependent on yours. @@ -383,7 +387,7 @@ This procedure will only work if you are the only person working on a set of com git push origin HEAD:refs/for/master ``` -### Amending a change of another author using git +#### Amending a change of another author using git When amending code from a different author, reviewer and original author should be coordinated in order to make sure that changes made by the reviewer are not reverted by the original author later. For that reason, it is recommended to avoid using the local copy of the branch. Instead, it is recommended to create a new local branch to work on every specific change, following the procedure below: @@ -417,7 +421,7 @@ When amending code from a different author, reviewer and original author should git push origin HEAD:refs/for/master ``` -### Amending a change of another author using git-review +#### Amending a change of another author using git-review 1. Follow the instructions in **[this link](05-git-review.md)** to install and configure git-review. 2. Download the change with `git-review` @@ -440,15 +444,60 @@ When amending code from a different author, reviewer and original author should $ git branch -D review/garciadeblas/1280 ``` -## Merging the contribution +### Merging the contribution 1. The **MDG Leader** can "Submit" the change only if +1 **"Code-Verif"** (from **Jenkins**) and at least one +2 **"Code-Review"**. 2. **Gerrit** reports the result of the code review to the corresponding bug in **Bugzilla** -## Fixing the author name / email +### Fixing the author name / email - Did you commit your changes with a wrong user name? Don't panic, see how [this can be fixed](https://www.everythingcli.org/git-like-a-pro-rewrite-author-history/) +## Proposing a new Feature + +Project Features go trough a discussion and approval process. + +To propose a new Feature, OSM uses [Gitlab](https://osm.etsi.org/gitlab). + +1. Go to [https://osm.etsi.org/gitlab/osm/features/-/issues/new](https://osm.etsi.org/gitlab/osm/features/-/issues/new) + +2. Create a **new Issue for your feature** + + - Title: A high level description of your feature (see some other examples in Gitlab) + - Type: Issue + - Description: The feature description, following the proposed template + A feature request is about functionality, not about implementation (that is the design) + Describe WHAT you are proposign to implement, and WHY it is important. + Do now describe HOW to do it. + +3. Set **Milestone: Proposed** + + TSC will only review Features ready to be discussed, and those will need to have a Miletone=Proposed. + +4. Pick **Labels** + + Pick labels for the modules you think are going to be affected + + +5. Submit Issue + +**PLEASE:** Do not set any + - other Milestone + - EPIC + - Asignee + - Weight + - Due Date + +TSC will review your Feature, and if approved, it will transition to the next steps +- **Proposed**: Proposed by a community member. Not approved yet. +- **Aproved**: Approved by TSC to be included in OSM +- **Design**: In the design phase, where HOW do to it will be discussed +- **Development**: It is being implemented +- **Testing**: Developer is testing it +- **Review**: Community s reviewing it +- **Completed**: It is completed, and merged +- **Abandoned**: It was abandoned + ## OSM CI/CD ![OSM CI/CD Workflow](assets/700px-OSM-CI-CD-workflow.png) diff --git a/README.md b/README.md index e9ea25a172ad3c34b746f7cd32e68c21b4e8304d..f4cd783486b2a8d4341949ffc56f18c74f778c83 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ ## Scope of the document This document collects Open Source MANO Developer Guide. +It is published at: [https://osm.etsi.org/docs/developer-guide](https://osm.etsi.org/docs/developer-guide) ## Guidelines for contributors @@ -19,10 +20,14 @@ Install the required packages: sudo -H python3 -m pip install -r requirements.txt ``` +Before proceeding, **make sure that there are no uncommitted changes in your workdir or your staging area** (in case of doubt, do all the corresponding `add`'s and `commit`'s). + Then run: ```bash +make clean make html +./fix_cross_references.sh ``` The generated HTML output is stored in `_build/html`. You can go to that folder and publish the content locally with a Simple HTTP Server in Python. diff --git a/env b/env new file mode 100644 index 0000000000000000000000000000000000000000..8389c4cde3fed9afcc9122872b422742ef0b5d52 --- /dev/null +++ b/env @@ -0,0 +1,9 @@ +#!/bin/bash +SERVER="ftp://osm-download.etsi.org" +FOLDER="developer-guide" +FTP_OPTS="" + +# Define your FTP credentials in a separate (private file) +# local/.credentials +# USERNAME= +# PASSWORD= diff --git a/fix_cross_references.sh b/fix_cross_references.sh new file mode 100755 index 0000000000000000000000000000000000000000..ab23e752b1f7042cf627e1ea2bf8b739900a779e --- /dev/null +++ b/fix_cross_references.sh @@ -0,0 +1,10 @@ +#!/bin/bash +# +# This is needed to fix a bug in sphinx +# Otherwise, cross-references in html will point to a .md file +# +for file in $(find _build -name "*.html") +do + sed -r -E -i "s/href=\"(.*)\.md\#/href=\"\1.html#/g" ${file} +done + diff --git a/upload-doc.sh b/upload-doc.sh index 3ee4f741fd1e86fb83f7028a191eef53da754441..e7dc23e472654adfbea625e5f5a1aa3488fd2f83 100755 --- a/upload-doc.sh +++ b/upload-doc.sh @@ -1,18 +1,42 @@ #!/bin/bash +# +# Script to upload documentation to ETSI site +# + +source ./env + +# +# Generate Statit Site +# make clean -for i in [0-1]*.md; do sed -i "s/\.md\#/\.html\#/g" $i; done make html -read -p "Please enter your username for FTP server (ETSI On Line account): " USER_INPUT -read -sp "Please enter your password for FTP server: " PASSWORD_INPUT -echo -lftp -u $USER_INPUT,$PASSWORD_INPUT ftp://osm-download.etsi.org << ! + +# +# Fix cross-references +# +./fix_cross_references.sh + +# +# Get credentias (file or interactive) +# +if [ local/.credentials ]; then + source local/.credentials + echo SERVER=${SERVER} + echo USERNAME=${USERNAME} +else + echo "Enter credentials for ${SERVER} (ETSI On Line account)" + read -p "Username: " USERNAME + read -sp "Password: " PASSWORD +fi + +lftp ${FTP_OPTS} -u ${USERNAME},${PASSWORD} ${SERVER} << ! set ftp:ssl-allow no lcd _build cd Documentation - mirror -R html developer-guide-new - rm -r developer-guide - mv developer-guide-new developer-guide + + mirror -R html ${FOLDER}-new + rm -r ${FOLDER}-old + mv ${FOLDER} ${FOLDER}-old + mv ${FOLDER}-new ${FOLDER} bye ! -git reset --hard -